跳轉到主要內容

​
常見安裝問題

​
Windows 安裝問題：WSL 中的錯誤

您可能在 WSL 中遇到以下問題： OS/平台偵測問題：如果您在安裝期間收到錯誤，WSL 可能正在使用 Windows npm。請嘗試：
  • 在安裝前執行 npm config set os linux
  • 使用 npm install -g @anthropic-ai/claude-code --force --no-os-check 安裝（請勿使用 sudo）
找不到 Node 錯誤：如果您在執行 claude 時看到 exec: node: not found，您的 WSL 環境可能正在使用 Windows 安裝的 Node.js。您可以使用 which npm 和 which node 確認，這些應該指向以 /usr/ 開頭的 Linux 路徑，而不是 /mnt/c/。要修復此問題，請嘗試透過您的 Linux 發行版的套件管理器或透過 nvm 安裝 Node。 nvm 版本衝突：如果您在 WSL 和 Windows 中都安裝了 nvm，在 WSL 中切換 Node 版本時可能會遇到版本衝突。這是因為 WSL 預設會匯入 Windows PATH，導致 Windows nvm/npm 優先於 WSL 安裝。 您可以透過以下方式識別此問題：
  • 執行 which npm 和 which node - 如果它們指向 Windows 路徑（以 /mnt/c/ 開頭），則正在使用 Windows 版本
  • 在 WSL 中使用 nvm 切換 Node 版本後功能損壞
要解決此問題，請修復您的 Linux PATH 以確保 Linux node/npm 版本優先： 主要解決方案：確保 nvm 在您的 shell 中正確載入 最常見的原因是 nvm 未在非互動式 shell 中載入。將以下內容新增到您的 shell 設定檔（~/.bashrc、~/.zshrc 等）： 
# Load nvm if it exists
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
或在您目前的工作階段中直接執行： 
source ~/.nvm/nvm.sh
替代方案：調整 PATH 順序 如果 nvm 已正確載入但 Windows 路徑仍優先，您可以在 shell 設定中明確地將 Linux 路徑前置到 PATH： 
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
避免停用 Windows PATH 匯入（appendWindowsPath = false），因為這會破壞從 WSL 輕鬆呼叫 Windows 可執行檔的能力。同樣，如果您在 Windows 開發中使用 Node.js，請避免從 Windows 解除安裝它。

​
Linux 和 Mac 安裝問題：權限或找不到命令錯誤

使用 npm 安裝 Claude Code 時，PATH 問題可能會阻止存取 claude。 如果您的 npm 全域前置詞不可由使用者寫入（例如 /usr 或 /usr/local），您也可能遇到權限錯誤。

​
建議的解決方案：原生 Claude Code 安裝

Claude Code 有一個原生安裝，不依賴 npm 或 Node.js。
Claude Code 原生安裝程式目前處於測試版。
使用以下命令執行原生安裝程式。 macOS、Linux、WSL： 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell： 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
此命令為您的作業系統和架構安裝適當的 Claude Code 版本，並在 ~/.local/bin/claude 新增符號連結。
確保您的系統 PATH 中有安裝目錄。
驗證安裝： 
claude doctor # Check installation health

​
權限和驗證

​
重複的權限提示

如果您發現自己反覆批准相同的命令，您可以使用 /permissions 命令允許特定工具在不需要批准的情況下執行。請參閱權限文件。

​
驗證問題

如果您遇到驗證問題：
  1. 執行 /logout 完全登出
  2. 關閉 Claude Code
  3. 使用 claude 重新啟動並再次完成驗證程序
如果問題仍然存在，請嘗試： 
rm -rf ~/.config/claude-code/auth.json
claude
這會移除您儲存的驗證資訊並強制進行乾淨登入。

​
效能和穩定性

​
高 CPU 或記憶體使用率

Claude Code 設計用於大多數開發環境，但在處理大型程式碼庫時可能會消耗大量資源。如果您遇到效能問題：
  1. 定期使用 /compact 來減少上下文大小
  2. 在主要任務之間關閉並重新啟動 Claude Code
  3. 考慮將大型建置目錄新增到您的 .gitignore 檔案

​
命令掛起或凍結

如果 Claude Code 似乎無回應：
  1. 按 Ctrl+C 嘗試取消目前操作
  2. 如果無回應，您可能需要關閉終端並重新啟動

​
搜尋和探索問題

如果搜尋工具、@file 提及、自訂代理和自訂斜杠命令無法運作，請安裝系統 ripgrep： 
# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep
然後在您的環境中設定 USE_BUILTIN_RIPGREP=0。

​
WSL 上搜尋結果緩慢或不完整

在 WSL 上跨檔案系統工作時的磁碟讀取效能損失可能導致在 WSL 上使用 Claude Code 時匹配數少於預期（但不是完全缺乏搜尋功能）。
在這種情況下，/doctor 會將搜尋顯示為正常。
解決方案：
  1. 提交更具體的搜尋：透過指定目錄或檔案類型來減少搜尋的檔案數量：“在 auth-service 套件中搜尋 JWT 驗證邏輯”或”在 JS 檔案中尋找 md5 雜湊的使用”。
  2. 將專案移至 Linux 檔案系統：如果可能，確保您的專案位於 Linux 檔案系統（/home/）而不是 Windows 檔案系統（/mnt/c/）。
  3. 改用原生 Windows：考慮在 Windows 上原生執行 Claude Code，而不是透過 WSL，以獲得更好的檔案系統效能。

​
IDE 整合問題

​
WSL2 上未偵測到 JetBrains IDE

如果您在 WSL2 上使用 Claude Code 搭配 JetBrains IDE，並收到”未偵測到可用的 IDE”錯誤，這可能是由於 WSL2 的網路設定或 Windows 防火牆阻止連線。

​
WSL2 網路模式

WSL2 預設使用 NAT 網路，這可能會阻止 IDE 偵測。您有兩個選項： 選項 1：設定 Windows 防火牆（建議）
  1. 找到您的 WSL2 IP 位址： 
    wsl hostname -I
# Example output: 172.21.123.456
  2. 以系統管理員身份開啟 PowerShell 並建立防火牆規則： 
    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
    （根據步驟 1 中的 WSL2 子網調整 IP 範圍）
  3. 重新啟動您的 IDE 和 Claude Code
選項 2：切換到鏡像網路 新增到您的 Windows 使用者目錄中的 .wslconfig： 
[wsl2]
networkingMode=mirrored
然後從 PowerShell 使用 wsl --shutdown 重新啟動 WSL。
這些網路問題僅影響 WSL2。WSL1 直接使用主機的網路，不需要這些設定。
如需其他 JetBrains 設定提示，請參閱我們的 IDE 整合指南。

​
報告 Windows IDE 整合問題（原生和 WSL）

如果您在 Windows 上遇到 IDE 整合問題，請建立問題並提供以下資訊：您是原生（git bash）還是 WSL1/WSL2、WSL 網路模式（NAT 或鏡像）、IDE 名稱/版本、Claude Code 擴充功能/外掛版本和 shell 類型（bash/zsh 等）

​
ESC 鍵在 JetBrains（IntelliJ、PyCharm 等）終端中無法運作

如果您在 JetBrains 終端中使用 Claude Code，且 ESC 鍵無法如預期中斷代理，這可能是由於與 JetBrains 預設快捷鍵的按鍵繫結衝突。 要修復此問題：
  1. 前往設定 → 工具 → 終端
  2. 執行以下任一操作：
    • 取消勾選”使用 Escape 將焦點移至編輯器”，或
    • 按一下”設定終端按鍵繫結”並刪除”切換焦點到編輯器”快捷鍵
  3. 套用變更
這允許 ESC 鍵正確中斷 Claude Code 操作。

​
Markdown 格式化問題

Claude Code 有時會產生缺少程式碼圍欄上語言標籤的 markdown 檔案，這可能會影響 GitHub、編輯器和文件工具中的語法醒目提示和可讀性。

​
程式碼區塊中缺少語言標籤

如果您在產生的 markdown 中注意到如下程式碼區塊： 
```
function example() {
  return "hello";
}
```
而不是正確標籤的區塊，例如： 
```javascript
function example() {
  return "hello";
}
```
解決方案：
  1. 要求 Claude 新增語言標籤：只需要求”請在此 markdown 檔案中的所有程式碼區塊新增適當的語言標籤。”
  2. 使用後處理掛鉤：設定自動格式化掛鉤以偵測並新增缺少的語言標籤。請參閱 markdown 格式化掛鉤範例以了解實作詳細資訊。
  3. 手動驗證：產生 markdown 檔案後，檢查它們是否有正確的程式碼區塊格式，如果需要，請要求更正。

​
間距和格式化不一致

如果產生的 markdown 有過多空白行或間距不一致： 解決方案：
  1. 要求格式化更正：要求 Claude”修復此 markdown 檔案中的間距和格式化問題。”
  2. 使用格式化工具：設定掛鉤以在產生的 markdown 檔案上執行 markdown 格式化程式（如 prettier）或自訂格式化指令碼。
  3. 指定格式化偏好設定：在您的提示或專案記憶體檔案中包含格式化要求。

​
Markdown 產生的最佳實踐

要最小化格式化問題：
  • 在要求中明確說明：要求”格式正確的 markdown，包含語言標籤的程式碼區塊”
  • 使用專案慣例：在 CLAUDE.md 中記錄您偏好的 markdown 風格
  • 設定驗證掛鉤：使用後處理掛鉤自動驗證和修復常見格式化問題

​
獲取更多幫助

如果您遇到此處未涵蓋的問題：
  1. 在 Claude Code 中使用 /bug 命令直接向 Anthropic 報告問題
  2. 檢查 GitHub 儲存庫以了解已知問題
  3. 執行 /doctor 檢查您的 Claude Code 安裝的健康狀況
  4. 直接詢問 Claude 有關其功能和特性 - Claude 內建存取其文件