​
常見安裝問題

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

您可能在 WSL 中遇到以下問題：

作業系統/平台檢測問題：如果您在安裝過程中收到錯誤，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 可執行檔的能力。同樣，如果您將 Node.js 用於 Windows 開發，請避免從 Windows 解除安裝 Node.js。

​
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 Code 可以執行，您可以遷移到本機安裝：

claude migrate-installer

這會將 Claude Code 移動到 ~/.claude/local/ 並在您的 shell 設定中設定別名。未來更新不需要 sudo。

遷移後，重新啟動您的 shell，然後驗證您的安裝：

在 macOS/Linux/WSL 上：

which claude  # Should show an alias to ~/.claude/local/claude

在 Windows 上：

where claude  # Should show path to claude executable

驗證安裝：

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. 如果沒有回應，您可能需要關閉終端機並重新啟動

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

如果您在 JetBrains 終端機中使用 Claude Code，而 ESC 鍵無法如預期中斷代理程式，這可能是由於與 JetBrains 預設快捷鍵的按鍵綁定衝突。

要修復此問題：

  1. 前往設定 → 工具 → 終端機
  2. 點選「覆蓋 IDE 快捷鍵」旁邊的「設定終端機按鍵綁定」超連結
  3. 在終端機按鍵綁定中，向下捲動到「切換焦點到編輯器」並刪除該快捷鍵

這將允許 ESC 鍵正確用於取消 Claude Code 操作，而不是被 PyCharm 的「切換焦點到編輯器」動作捕獲。

​
搜尋和發現問題

如果搜尋工具、@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，以獲得更好的檔案系統效能。

​
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 內建存取其文件的能力