Claude Code 错误排查指南：从症状到解决方案

遇到问题不要慌，系统排查是关键。

Claude Code 功能强大，但出问题时也让人头疼。

这篇文章按症状分类，帮助你快速定位问题并找到解决方案。

一、快速诊断

运行 /doctor

最简单的方法——让 Claude Code 自己诊断：

/doctor

/doctor 会自动检查： - 安装状态 - 配置文件 - MCP 服务器 - 上下文使用情况 - 网络连接

如果 claude 命令都无法启动，在终端运行：

claude doctor

常见问题速查表

检查 PATH

二、安装问题

2.1 command not found

症状：

claude

原因：Claude Code 未添加到 PATH。

解决方案：

which claude # macOS/Linux

where claude # Windows

echo 'export PATH="

source ~/.zshrc

2.2 安装脚本返回 HTML

症状：

curl -fsSL https://claude.ai/install.sh | sh

原因：网络被拦截，返回的是 HTML 而非脚本。

解决方案：

npm install -g @anthropic-ai/claude-code

curl -Lo claude https://downloads.claude.ai/claude-code-releases/latest/claude-macos-x64

chmod +x claude

sudo mv claude /usr/local/bin/

curl -Lo claude https://downloads.claude.ai/claude-code-releases/latest/claude-linux-x64

chmod +x claude

sudo mv claude /usr/local/bin/

2.3 TLS/SSL 错误

症状：

原因：CA 证书问题，常见于企业网络。

解决方案：

brew install ca-certificates

sudo apt install ca-certificates

sudo update-ca-certificates

export NODE_EXTRA_CA_CERTS=/path/to/certificate.pem

export SSL_CERT_FILE=/path/to/certificate.pem

2.4 Linux 安装被 Killed

症状：

原因：内存不足。

解决方案：

sudo fallocate -l 2G /swapfile

sudo chmod 600 /swapfile

sudo mkswap /swapfile

sudo swapon /swapfile

三、登录与认证问题

3.1 403 Forbidden

症状：

403 Forbidden after login

原因：账户没有 Claude Code 权限。

解决方案：

1. 确认订阅：需要 Pro、Team 或 Enterprise 订阅

2. 检查组织状态：联系管理员确认组织未禁用

3. 重置登录：

claude logout

claude login

3.2 OAuth 错误

症状：

OAuth error: Invalid code

原因：OAuth 流程中断或过期。

解决方案：

claude logout

claude login

claude login --browser

3.3 WSL2 登录失败

症状：WSL2 中 OAuth 登录失败。

解决方案：

claude login --browser

cp -r /mnt/c/Users/YOUR_USER/.claude ~/.claude

3.4 企业认证失败

症状：

Could not load the default credentials

ChainedTokenCredential authentication failed

原因：Bedrock/Vertex/Foundry 凭据配置错误。

解决方案：

echo $ANTHROPIC_API_KEY

aws configure

export CLAUDE_CODE_USE_BEDROCK=1

gcloud auth application-default login

export CLAUDE_CODE_USE_VERTEX=1

export CLAUDE_CODE_USE_FOUNDRY=1

四、性能问题

4.1 高 CPU 或内存占用

症状：Claude Code 占用大量 CPU 或内存。

原因：上下文过大、大量文件搜索。

解决方案：

/compact

/context

/clear

echo "node_modules/\nbuild/\ndist/" >> .gitignore

诊断内存问题：

/heapdump

4.2 自动压缩循环失败

症状：

Autocompact is thrashing: the context refilled to the limit...

原因：自动压缩成功后，大文件或工具输出立即填满上下文，多次循环。

解决方案：

/compact keep only the plan and the diff

/clear

4.3 命令卡住不动

症状：Claude Code 无响应。

解决方案：

Ctrl+C

claude --resume

4.4 响应变慢

症状：Claude 响应越来越慢。

原因：上下文过大、上下文污染。

解决方案：

/context

/compact

五、搜索问题

5.1 搜索找不到文件

症状：Search 工具、@file 提及找不到文件。

原因：内置 ripgrep 二进制不兼容。

解决方案：

brew install ripgrep

sudo apt install ripgrep

winget install BurntSushi.ripgrep.MSVC

export USE_BUILTIN_RIPGREP=0

5.2 WSL 搜索结果不完整

症状：WSL 中搜索返回的结果比预期少。

原因：WSL 跨文件系统的性能惩罚。

解决方案：

六、MCP 问题

6.1 MCP 服务器无法连接

症状：

MCP server "xxx" failed to connect

解决方案：

/mcp

tail -f ~/.claude/logs/mcp.log

/mcp restart xxx

cat .mcp.json

cat ~/.claude/.mcp.json

which npx

which uvx

6.2 MCP 工具调用超时

症状：

MCP tool call timed out

解决方案：

export MCP_TIMEOUT=30000 # 30 秒

tail -f ~/.claude/logs/mcp.log

6.3 MCP 服务器认证失败

症状：

Authentication failed

API key invalid

解决方案：

echo $API_KEY

curl -H "Authorization: Bearer $API_KEY" https://api.example.com/test

七、配置问题

7.1 配置不生效

症状：修改 settings.json 后配置不生效。

解决方案：

cat .claude/settings.json | python -m json.tool

7.2 Hooks 不触发

症状：配置了 Hooks 但没有触发。

解决方案：

/hooks

cat .claude/settings.json | python -m json.tool

ls -la .claude/hooks/

chmod +x .claude/hooks/*.sh

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | .claude/hooks/my-hook.sh

echo $? # 应该返回 0

7.3 CLAUDE.md 规则被忽略

症状：CLAUDE.md 中的规则没有被遵守。

解决方案：

/compact

八、API 错误

8.1 429 Too Many Requests

症状：

API Error: 429 Too Many Requests

原因：请求频率超限。

解决方案：

8.2 500/529 服务器错误

症状：

API Error: 500 Internal Server Error

API Error: 529 Overloaded

原因：服务器端问题。

解决方案：

claude --resume

8.3 模型不可用

症状：

model not found

you may not have access to it

原因：账户无权使用该模型。

解决方案：

九、日志与调试

9.1 查看日志

~/.claude/logs/

tail -f ~/.claude/logs/claude.log

tail -f ~/.claude/logs/mcp.log

grep -i error ~/.claude/logs/*.log

9.2 调试模式

export CLAUDE_DEBUG=1

export MCP_DEBUG=1

claude

9.3 检查环境

claude --version

which claude

ls -la ~/.claude/

ls -la .claude/

env | grep CLAUDE

env | grep ANTHROPIC

十、问题排查流程

遇到问题时，按这个流程排查：

1. 运行 /doctor

↓

2. 检查错误信息

↓

3. 查看日志

tail -f ~/.claude/logs/claude.log

↓

4. 搜索错误信息

在文档或 GitHub Issues 中搜索

↓

5. 尝试基本修复

- 重启 Claude Code

- 清除上下文 /compact 或 /clear

- 重新登录 claude logout && claude login

↓

6. 仍然无法解决？

- 提交 Issue: https://github.com/anthropics/claude-code/issues

- 附上 /doctor 输出和日志

总结

排查原则：

运行 /doctor

预防措施：

上下文超 50% 就 /compact

记住：大多数问题都能通过重启、重登录、清除上下文解决。如果仍然卡住，日志是最好的朋友。