11 故障排查

cuizhenjie2026-01-052026-01-05

遇到问题别慌

用工具总会遇到问题,Claude Code 也不例外。这一章我想分享一些常见问题的解决方法,大部分都是我自己遇到过或者从社区里学来的。

说实话,我刚用 Claude Code 的时候也踩过不少坑。命令找不到、权限错误、API 密钥无效,这些我都遇到过。但慢慢就发现,大部分问题都有规律可循,掌握了排查方法就不用担心了。

安装那些事

命令找不到

这是最常见的问题:

1 2	claude --version # command not found: claude

别慌,一般就是 PATH 的问题。

先检查安装是否成功:

1	npm list -g @anthropic-ai/claude-code

然后检查 PATH:

1	echo $PATH \| grep -i npm

如果没有,添加到 PATH:

1
2
3

# 在 ~/.bashrc 或 ~/.zshrc 中
export PATH=$(npm config get prefix)/bin:$PATH
source ~/.bashrc

我第一次安装就遇到这个问题,折腾了好久才明白是 PATH 没配置好。

权限错误

这种错误也挺常见:

1	EACCES: permission denied

有两个解决方案。

用 sudo 安装:

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

或者修复 npm 权限(我更推荐这个方法):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

第二种方法更好,因为以后全局安装其他包也不会有权限问题了。

Node.js 版本过低

1	Error: Claude Code requires Node.js version 20.19.0 or higher

用 nvm 安装正确版本:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

nvm 真的挺好用的,可以在不同 Node.js 版本之间切换。我一般都会用 LTS 版本,稳定一些。

API 相关问题

API 密钥无效

1	Error: Invalid API key

先验证密钥格式:

1 2	echo $ANTHROPIC_API_KEY # 应该以 sk-ant- 开头

如果不对,重新设置:

1	export ANTHROPIC_API_KEY="sk-ant-your-new-key"

还要确认密钥在 Console 里是有效的,去 https://console.anthropic.com/ 检查一下。

我遇到过一次密钥过期的问题,重新生成就好了。

API 限额超出

1	Error: Rate limit exceeded

这个说明你用太多了。

可以检查使用情况:

1	claude "检查我的 API 使用情况"

然后等限额重置(一般按小时或天算),或者升级 API 计划。

也可以优化提示词,减少 token 使用:

1 2	# 用简洁的提示词 claude "简洁回答:..."

我一般会优化提示词,避免重复的上下文,这样能省不少 token。

网络连接失败

1	Error: Failed to connect to Anthropic API

先检查网络:

1	ping api.anthropic.com

如果需要代理,配置一下:

1 2	export HTTP_PROXY=http://proxy:port export HTTPS_PROXY=http://proxy:port

还要检查防火墙设置,有时候公司网络会限制访问。

性能问题

响应太慢

这个挺常见的,原因有好几个。

上下文太大会很慢:

# 别这样
claude "分析整个项目"

# 这样更好
claude --add-dir ./src/auth "分析认证模块"

模型选择也很重要:

# 简单任务用 Haiku
claude --model haiku "简单问题"

# 复杂任务才用 Sonnet
claude --model sonnet "复杂架构设计"

网络延迟也有影响,检查一下:

1	ping api.anthropic.com

内存占用高

这个也挺烦的。

限制上下文大小:

1
2
3

# 用 .claudeignore 排除不必要的文件
echo "node_modules/" >> .claudeignore
echo "*.log" >> .claudeignore

分批处理大任务:

# 别一次性处理
claude "重构整个项目"

# 分模块处理
claude "重构 user 模块"
claude "重构 order 模块"

我处理大型项目的时候都会分模块,这样不仅快,而且更容易出问题也容易定位。

输出质量问题

生成的代码有错误

这种情况我遇到过不少。

提供更多上下文:

1	claude "这是项目结构:[结构]请生成符合这个结构的代码"

明确要求:

1	claude "生成代码,要求:使用 TypeScript、遵循 ESLint 规则、包含错误处理、添加类型提示"

让它自己审查:

1	claude "生成代码并审查潜在问题"

这个技巧特别有用,让它自己检查自己生成的代码,能发现很多问题。

理解不准确

有时候 Claude 理解不了你的需求。

用示例:

1	claude "类似这样的功能:[示例]请实现..."

分步确认:

1 2	claude "确认你的理解:我需要..." claude "基于你的理解,实现..."

换个模型:

1 2	# 用更强大的模型 claude --model sonnet "复杂任务"

调试技巧

启用调试模式

1	claude --debug "你的问题"

这样能看到详细的请求和响应信息,排查问题很有用。

查看日志

# Claude Code 日志位置
~/.claude/logs/

# 查看最新日志
tail -f ~/.claude/logs/claude-code.log

测试连接

1	claude "测试连接"

这个能快速确认 API 是否正常。

重置配置

实在不行就重置:

# 备份配置
cp -r ~/.claude ~/.claude.backup

# 重置配置
rm -rf ~/.claude
claude "重新配置"

我一般不会轻易重置,除非实在找不到问题所在。

常见错误代码

错误代码	含义	解决方案
401	未授权	检查 API 密钥
429	请求过多	等待或升级计划
500	服务器错误	稍后重试
503	服务不可用	检查状态页面

401 一般是密钥问题,429 是用多了,500 和 503 是服务器的问题,只能等。

获取帮助

官方资源

我一般先看文档,实在不行再去 GitHub Issues 看看有没有人遇到类似问题。

社区支持

Discord 服务器、Reddit 社区、Stack Overflow 这些地方也能找到帮助。

报告问题

如果真的要报告问题,记得提供这些信息:

Claude Code 版本:

1	claude --version

完整的错误信息、复现步骤、系统信息:

1
2
3

uname -a
node --version
npm --version

信息越详细,越容易定位问题。

预防性维护

定期更新

1 2	npm update -g @anthropic-ai/claude-code claude --version

我一般会定期更新,新版本会修复很多 bug。

清理缓存

1	rm -rf ~/.claude/cache/*

有时候缓存会出问题,清理一下就好了。

备份配置

1	cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)

定期备份配置,出问题了能快速恢复。

我的使用经验

遇到问题别慌,大部分问题都有解决方案。先检查基本的东西:网络、密钥、版本、权限。

用调试模式能快速定位问题。如果真的解决不了,去官方文档和社区找找,大概率别人也遇到过。

定期更新、清理缓存、备份配置,这些习惯能帮你避免很多问题。

性能优化这事儿,我觉得关键是控制上下文、选择合适的模型、优化提示词。这样既快又省钱。

下一步

恭喜你完成了主要的学习内容!接下来我们聊聊怎么持续学习和进阶。

第十二章:下一步

最后一章我们会探讨进阶学习资源、社区和持续学习、Claude Code 的未来。