本文整理 Claude Code 最常见的问题和解法，按场景分类，对号入座直接解决。
一、安装问题
1. command not found: claude
PATH 未配置。
bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc2. 安装脚本返回 HTML
bash
curl -fsSL https://claude.ai/install.sh -o install.sh
bash install.sh3. Linux 低内存服务器安装 Killed
bash
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
curl -fsSL https://claude.ai/install.sh | bash4. TLS/SSL 连接错误
bash
sudo apt-get install -y ca-certificates
export HTTPS_PROXY=http://proxy.company.com:8080
curl -fsSL https://claude.ai/install.sh | bash5. macOS dyld: cannot load
bash
xattr -d com.apple.quarantine $(which claude)
# 或用 Homebrew 安装
brew install --cask claude-code二、登录和认证问题
6. OAuth error: Invalid code（WSL2 常见）
bash
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude /login
# 或直接用 API Key
export ANTHROPIC_API_KEY=sk-ant-xxxxx
claude7. 403 Forbidden
需要 Claude Pro/Max/Teams/Enterprise 订阅或 Console 账号。
8. 重复权限确认弹窗
json
{
"permissions": {
"allow": ["Bash(npm *)", "Bash(git *)", "Read(**)", "Write(src/**)"]
}
}三、性能和稳定性问题
9. 命令卡住不动
bash
# Ctrl+C 中断
pkill -f "claude"
curl -s https://api.anthropic.com/health10. 上下文越来越慢
bash
/status
/compact
/clear11. CPU/内存占用过高
在 .gitignore 里排除无关目录（node_modules/、dist/、build/ 等），Claude Code 尊重 gitignore 规则。
四、IDE 集成问题
12. VS Code 扩展找不到 claude 命令
Settings -> Extensions -> Claude Code -> Claude command，填写完整路径。
13. JetBrains IDE 未被检测
bash
# 从 IDE 内置终端启动
claude
/ide14. JetBrains ESC 键无法中断
Settings -> Tools -> Terminal -> 取消勾选 "Move focus to the editor with Escape"
五、配置和行为问题
15. CLAUDE.md 规则没有生效
常见原因：文件超过 200 行（降低遵从度）、规则存在冲突、/compact 后暂时失效（正常现象）。
bash
wc -l CLAUDE.md16. Auto Memory 记住了错误内容
bash
/memory17. Hooks 没有触发
bash
/hooks
bash ~/.claude/hooks/your-hook.sh # 独立测试六、WSL2 特有问题
18. WSL2 搜索速度很慢
把项目放在 Linux 文件系统而非 /mnt/c/：
- 好：/home/user/projects/
- 差：/mnt/c/Users/user/projects/
19. WSL2 JetBrains 连接失败
在 /etc/wsl.conf 里设置 networkingMode=mirrored，然后 wsl --shutdown 重启。
七、重置和恢复
20. 配置文件位置
bash
~/.claude/settings.json # 个人全局配置
~/.claude/auth.json # 认证凭证
.claude/settings.json # 项目配置21. 重置配置
bash
cp -r ~/.claude ~/.claude.bak # 先备份
rm ~/.claude/auth.json # 只清认证22. 获取更多帮助
bash
claude /help
claude --version官方文档：https://docs.anthropic.com/en/docs/claude-code/troubleshooting
来源：Troubleshooting - Claude Code Docs | Anthropic 官方文档