​
常見安裝問題

​
Linux 權限問題

使用 npm 安裝 Claude Code 時，如果您的 npm 全域前綴不是使用者可寫入的（例如 /usr 或 /usr/local），您可能會遇到權限錯誤。

​
建議解決方案：建立使用者可寫入的 npm 前綴

最安全的方法是設定 npm 使用您家目錄內的目錄：

# 首先，儲存現有全域套件清單以便稍後遷移
npm list -g --depth=0 > ~/npm-global-packages.txt

# 為您的全域套件建立目錄
mkdir -p ~/.npm-global

# 設定 npm 使用新的目錄路徑
npm config set prefix ~/.npm-global

# 注意：根據您的 shell，將 ~/.bashrc 替換為 ~/.zshrc、~/.profile 或其他適當的檔案
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 套用新的 PATH 設定
source ~/.bashrc

# 現在在新位置重新安裝 Claude Code
npm install -g @anthropic-ai/claude-code

# 可選：在新位置重新安裝您之前的全域套件
# 查看 ~/npm-global-packages.txt 並安裝您想要保留的套件

建議使用此解決方案，因為它：

  • 避免修改系統目錄權限
  • 為您的全域 npm 套件建立乾淨、專用的位置
  • 遵循安全最佳實務

​
系統復原：如果您已執行變更系統檔案擁有權和權限或類似的命令

如果您已經執行了變更系統目錄權限的命令（例如 sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr）且您的系統現在損壞（例如，如果您看到 sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set），您需要執行復原步驟。

Ubuntu/Debian 復原方法：

  1. 重新開機時，按住 SHIFT 鍵存取 GRUB 選單

  2. 選擇「Advanced options for Ubuntu/Debian」

  3. 選擇復原模式選項

  4. 選擇「Drop to root shell prompt」

  5. 將檔案系統重新掛載為可寫入：

    mount -o remount,rw /

  6. 修復權限：

    # 恢復 root 擁有權
chown -R root:root /usr
chmod -R 755 /usr

# 確保 /usr/local 由您的使用者擁有以供 npm 套件使用
chown -R YOUR_USERNAME:YOUR_USERNAME /usr/local

# 為關鍵二進位檔案設定 setuid 位元
chmod u+s /usr/bin/sudo
chmod 4755 /usr/bin/sudo
chmod u+s /usr/bin/su
chmod u+s /usr/bin/passwd
chmod u+s /usr/bin/newgrp
chmod u+s /usr/bin/gpasswd
chmod u+s /usr/bin/chsh
chmod u+s /usr/bin/chfn

# 修復 sudo 設定
chown root:root /usr/libexec/sudo/sudoers.so
chmod 4755 /usr/libexec/sudo/sudoers.so
chown root:root /etc/sudo.conf
chmod 644 /etc/sudo.conf

  7. 重新安裝受影響的套件（可選但建議）：

    # 儲存已安裝套件清單
dpkg --get-selections > /tmp/installed_packages.txt

# 重新安裝它們
awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y

  8. 重新開機：

    reboot
替代 Live USB 復原方法：

如果復原模式無法運作，您可以使用 live USB：

  1. 從 live USB 開機（Ubuntu、Debian 或任何 Linux 發行版）

  2. 找到您的系統分割區：

    lsblk

  3. 掛載您的系統分割區：

    sudo mount /dev/sdXY /mnt  # 將 sdXY 替換為您實際的系統分割區

  4. 如果您有單獨的開機分割區，也要掛載它：

    sudo mount /dev/sdXZ /mnt/boot  # 如果需要

  5. Chroot 進入您的系統：

    # 對於 Ubuntu/Debian：
sudo chroot /mnt

# 對於基於 Arch 的系統：
sudo arch-chroot /mnt

  6. 遵循上述 Ubuntu/Debian 復原方法的步驟 6-8

復原系統後，遵循上述建議解決方案設定使用者可寫入的 npm 前綴。

​
自動更新器問題

如果 Claude Code 無法自動更新，可能是由於您的 npm 全域前綴目錄的權限問題。遵循上述建議解決方案來修復此問題。

如果您偏好停用自動更新器，您可以將 DISABLE_AUTOUPDATER 環境變數設定為 1

​
權限和驗證

​
重複的權限提示

如果您發現自己重複核准相同的命令，您可以使用 /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 的「切換焦點到編輯器」動作捕獲。

​
取得更多協助

如果您遇到此處未涵蓋的問題：

  1. 在 Claude Code 中使用 /bug 命令直接向 Anthropic 回報問題
  2. 檢查 GitHub 儲存庫以了解已知問題
  3. 執行 /doctor 檢查您的 Claude Code 安裝健康狀況