遇到问题别慌，这里整理了 Claude Code 最常见的报错原因和解决方法。
安装类问题
❌ claude: command not found
原因：npm 全局包路径不在 PATH 里。
bash
# 找到全局 npm bin 路径
npm bin -g
# 通常是 /usr/local/bin 或 ~/.npm-global/bin 或 ~/.nvm/versions/.../bin
# 加入 PATH（以 ~/.bashrc 为例）
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc
# 验证
claude --version❌ npm WARN notsup Unsupported engine
bash
node --version # 需要 >= 18
# 升级方法（推荐 nvm）：
nvm install --lts && nvm use --lts
npm install -g @anthropic-ai/claude-code❌ EACCES: permission denied 安装失败
bash
# 不要用 sudo npm，改用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts
npm install -g @anthropic-ai/claude-code登录 / 认证类问题
❌ Authentication failed / OAuth 登录无法完成
原因：浏览器无法自动打开，或 OAuth 回调被阻止。
bash
# 方法 1：重新触发登录
claude auth logout
claude # 重新打开浏览器登录
# 方法 2：改用 API Key（服务器/无 GUI 环境）
export ANTHROPIC_API_KEY="sk-ant-你的Key"
claude # 直接使用 API Key，跳过 OAuth❌ Invalid API key / 401 Unauthorized
bash
# 检查 Key 是否正确设置
echo $ANTHROPIC_API_KEY
# 确认 Key 没有过期（在 console.anthropic.com 重新生成）
# 重新设置
export ANTHROPIC_API_KEY="sk-ant-新的Key"
# 持久化到配置文件
echo 'export ANTHROPIC_API_KEY="sk-ant-新的Key"' >> ~/.bashrc❌ Your account has been rate limited
账号触发了安全限流，通常是短时间内请求量异常。等待 60 分钟后再试，或检查是否有脚本在循环调用。
连接类问题
❌ Network error / ECONNREFUSED / Unable to connect
bash
# 1. 检查网络
curl -I https://api.anthropic.com
# 2. 如需代理
export HTTPS_PROXY="http://proxy-host:port"
export HTTP_PROXY="http://proxy-host:port"
claude
# 3. 检查防火墙
# 确保 api.anthropic.com:443 可访问❌ SSL certificate verify failed
bash
# 企业内网常见问题（SSL 拦截）
# 方法：设置自定义 CA 证书
export NODE_EXTRA_CA_CERTS="/path/to/company-ca.crt"
claude❌ Request timeout
bash
# 增大超时时间
export CLAUDE_REQUEST_TIMEOUT=120000 # 120 秒
# 如果是复杂任务导致超时，考虑拆分任务使用中的问题
❌ Context window exceeded / 上下文超出限制
原因：对话历史或文件内容超出模型 200K token 上限。
解决方案：
bash
# 1. 开启新会话（清空历史）
/clear
# 2. 压缩对话历史
/compact
# 3. 避免一次加载过多文件
# 不要：把整个项目的所有文件都告诉 Claude
# 而是：告诉 Claude 你需要它看哪几个具体文件❌ 输出中断 / 回复不完整
bash
# 增大 max tokens（在 settings.json）
{
"model": {
"maxTokens": 8192
}
}
# 或让 Claude 继续
"继续上面的内容"
"Please continue from where you left off"❌ Permission denied 无法读取/写入文件
bash
# 检查文件权限
ls -la problematic-file
# Claude Code 默认在当前目录工作
# 确保你在正确的项目目录里启动
cd /correct/project/path
claude
# 如果是 /tmp 等特殊目录，可能需要配置允许路径
# 在 settings.json 添加：
{
"permissions": {
"allow": ["/tmp", "/home/user/projects"]
}
}❌ Claude 拒绝执行某些操作（I can't do that）
通常是安全限制触发。解决方案：
- 更清晰地描述意图（说明为什么需要）
- 拆分成更小的步骤
- 在 CLAUDE.md 里预先说明项目上下文和授权范围
Git 相关问题
❌ Git 操作失败 / fatal: not a git repository
bash
# 确认在 Git 仓库内
git status
# 如果不是，初始化
git init❌ Claude 提交了不该提交的文件
bash
# 检查 .gitignore 是否完善
cat .gitignore
# 在 CLAUDE.md 里明确说明
## Git 规范
# - 不要提交 .env 文件
# - 不要提交 node_modules/
# - 每次提交前检查 git diffWindows 特有问题
❌ Windows PowerShell 中文乱码
powershell
# 设置 UTF-8 编码
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONIOENCODING = "utf-8"❌ WSL2 中 claude 命令无法访问 Windows 文件
bash
# 在 WSL2 中访问 Windows 文件用 /mnt/c/
cd /mnt/c/Users/YourName/Projects
# 但建议把项目放到 WSL 文件系统内，性能更好
cp -r /mnt/c/Users/YourName/Projects/myapp ~/projects/日志与诊断
bash
# 查看详细日志
claude --verbose
# 检查配置
claude config list
# 重置所有配置（最后手段）
claude auth logout
rm -rf ~/.claude
npm install -g @anthropic-ai/claude-code
claude # 重新初始化来源：Claude Code Troubleshooting - Anthropic 官方文档