​
常見安裝問題

​
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. 前往 Settings → Tools → Terminal
  2. 點擊「Override IDE Shortcuts」旁邊的「Configure terminal keybindings」超連結
  3. 在終端快捷鍵中，向下滾動到「Switch focus to Editor」並刪除該快捷鍵

這將允許 ESC 鍵正確地用於取消 Claude Code 操作，而不是被 PyCharm 的「Switch focus to Editor」動作捕獲。

​
獲取更多幫助

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

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