故障排查指南

Claude Code 常见问题的诊断与解决方案，帮你快速定位和修复问题

故障排查指南 ¶

使用 Claude Code 过程中遇到问题别慌。本指南按照「快速自检 → 逐步排查 → 解决方案」的流程组织，帮你高效定位和解决问题。

快速自检 ¶

遇到问题时，先做这三步快速检查，80% 的问题在这一步就能定位。

1. 检查 Claude Code 版本 ¶

claude --version

确认你使用的是最新版本。Claude Code 更新非常频繁，很多问题在新版本中已经修复。

升级到最新版：

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

2. 运行自动诊断 ¶

claude /doctor

/doctor 命令会自动检查：

Node.js 版本是否满足要求（≥ 18）
API Key 是否有效
网络连接是否正常
配置文件是否有语法错误

3. 确认 Node.js 版本 ¶

Claude Code 要求 Node.js 18 或更高版本：

node --version
# 应该输出 v18.x.x 或更高

如果版本过低，请升级：

# 使用 nvm 管理 Node.js 版本（推荐）
nvm install 22
nvm use 22

# 或直接下载安装
# 访问 https://nodejs.org/ 下载 LTS 版本

安装问题 ¶

npm install 权限错误 ¶

症状：

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

解决方案 1：使用 sudo（快速但不推荐长期使用）

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

解决方案 2：修改 npm 全局目录（推荐）

# 创建用户级别的全局包目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 添加到 PATH（写入 ~/.bashrc 或 ~/.zshrc）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安装
npm install -g @anthropic-ai/claude-code

解决方案 3：使用 nvm 管理 Node.js

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc

# 安装并使用 Node.js
nvm install 22
nvm use 22

# nvm 安装的 Node.js 不需要 sudo
npm install -g @anthropic-ai/claude-code

网络问题导致安装失败 ¶

症状：

npm ERR! network request to https://registry.npmjs.org/ failed
npm ERR! code ETIMEDOUT

解决方案：使用国内镜像源

# 临时使用淘宝镜像
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 或者永久设置镜像源
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

如果你使用代理：

# 设置 npm 代理
npm config set proxy http://你的代理地址:端口
npm config set https-proxy http://你的代理地址:端口

# 安装完成后可以取消代理设置
npm config delete proxy
npm config delete https-proxy

Windows PowerShell 执行策略 ¶

症状：

claude : File C:\Users\xxx\AppData\Roaming\npm\claude.ps1 cannot be loaded
because running scripts is disabled on this system.

解决方案：

# 以管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 然后重新运行 claude
claude

或者使用 CMD 代替 PowerShell：

# 在 CMD 中直接运行
claude

连接问题 ¶

连接问题是中国用户最常遇到的问题类型。

API Key 格式错误 ¶

QCode.cc 的 API Key 格式：

cr_xxxxxxxxxxxxxxxx

注意前缀是 cr_，不是 Anthropic 官方的 sk-ant-。

检查 API Key 配置：

# 查看当前环境变量
echo $ANTHROPIC_API_KEY

# 正确设置（QCode.cc 密钥）
export ANTHROPIC_API_KEY="cr_你的密钥"

常见错误：

错误	说明
密钥前后有空格	`cr_ xxx` → `cr_xxx`
使用了官方密钥格式	`sk-ant-xxx` 是 Anthropic 官方密钥，不是 QCode.cc 密钥
密钥被截断	检查是否完整复制了整个密钥
使用了过期密钥	在 QCode.cc Dashboard 确认密钥状态

ANTHROPIC_BASE_URL 配置错误 ¶

使用 QCode.cc 服务时，需要正确设置 Base URL：

# QCode.cc 的 Base URL
export ANTHROPIC_BASE_URL="https://你的服务地址"

排查步骤：

# 1. 检查当前配置
echo $ANTHROPIC_BASE_URL

# 2. 确认 URL 格式正确
#    - 必须以 https:// 开头
#    - 末尾不要带斜杠 /
#    - 不要包含路径（如 /v1/messages）

# 正确示例
export ANTHROPIC_BASE_URL="https://api.example.com"

# 错误示例
export ANTHROPIC_BASE_URL="http://api.example.com"      # 缺少 https
export ANTHROPIC_BASE_URL="https://api.example.com/"     # 多余的斜杠
export ANTHROPIC_BASE_URL="https://api.example.com/v1"   # 多余的路径

代理/VPN 导致连接失败 ¶

症状：

Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND api.example.com

排查步骤：

# 1. 检查代理是否正确设置
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

# 2. 测试网络连通性
curl -v https://你的服务地址/health

# 3. 如果使用代理，确保 Claude Code 能使用它
export HTTP_PROXY="http://代理地址:端口"
export HTTPS_PROXY="http://代理地址:端口"

# 4. 如果不需要代理但设置了代理，取消设置
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

VPN 注意事项：

确保 VPN 没有拦截 API 请求
某些 VPN 的分流规则可能影响 API 连接
如果 VPN 导致问题，尝试将 API 域名加入直连规则

SSL/TLS 证书问题 ¶

症状：

Error: unable to verify the first certificate
Error: self signed certificate in certificate chain

解决方案：

# 方案 1：更新系统 CA 证书
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
brew install ca-certificates

# 方案 2：如果是企业网络的中间人证书，设置 Node.js 信任
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.crt"

# 方案 3：临时跳过证书验证（仅用于测试，不建议长期使用）
export NODE_TLS_REJECT_UNAUTHORIZED=0

测试连接 ¶

用 curl 直接测试 API 连通性：

# 测试基础连通
curl -s -o /dev/null -w "%{http_code}" \
  https://你的服务地址/health

# 测试 API 调用（替换为你的密钥和地址）
curl https://你的服务地址/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

期望结果：

健康检查返回 200
API 调用返回 JSON 响应

常见问题对照：

curl 结果	可能原因	解决方案
`connection refused`	服务地址错误或服务未运行	检查 ANTHROPIC_BASE_URL
`connection timeout`	网络不通或被防火墙拦截	检查网络/代理设置
`401 Unauthorized`	API Key 无效	检查密钥是否正确
`403 Forbidden`	密钥无权限	联系服务提供商
SSL 相关错误	证书问题	参考上方 SSL 部分

权限问题 ¶

文件读写权限不足 ¶

症状：

Error: EACCES: permission denied, open '/path/to/file'

解决方案：

# 1. 检查文件权限
ls -la /path/to/file

# 2. 确保当前用户有读写权限
chmod u+rw /path/to/file

# 3. 检查目录权限（Claude 创建新文件时需要目录写权限）
chmod u+w /path/to/directory

# 4. 如果是 root 创建的文件，更改所有者
sudo chown $(whoami) /path/to/file

Claude Code 的权限配置：

Claude Code 有一套权限系统来控制它能执行哪些操作。如果你发现 Claude 被阻止执行某个操作：

# 查看当前权限设置
claude /permissions

# 在 settings.json 中配置允许的目录
# ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read files in /home/user/projects/**",
      "Write files in /home/user/projects/**",
      "Execute bash commands"
    ]
  }
}

Git 操作被拒绝 ¶

症状：

fatal: unable to access 'https://github.com/xxx/xxx.git/':
The requested URL returned error: 403

解决方案：

# 1. 检查 Git 配置
git config --list

# 2. 确认 SSH 密钥或 Token 配置
ssh -T git@github.com          # 测试 SSH 连接
gh auth status                  # 测试 GitHub CLI 认证

# 3. 如果是 HTTPS，检查凭证
git config credential.helper    # 查看凭证管理方式

# 4. 确保 Claude Code 在正确的 Git 仓库中
git status                      # 确认在仓库目录内

Bash 命令执行失败 ¶

Claude Code 执行 bash 命令时可能需要你确认。如果命令反复被拒：

# 查看权限配置
claude /permissions

# 如果是你信任的项目，可以在 CLAUDE.md 中配置允许的命令
# CLAUDE.md
## 允许执行的命令
allowedTools:

  - Bash(npm run *)
  - Bash(pnpm *)
  - Bash(git *)
  - Bash(docker compose *)

性能问题 ¶

响应速度慢 ¶

可能原因和解决方案：

原因	诊断方法	解决方案
网络延迟	`ping 服务地址`	检查网络/代理
使用了 Opus 模型	`/model` 查看	切换到 Sonnet
上下文太大	`/cost` 查看 token 数	`/compact` 压缩
服务端负载高	检查 HTTP 响应时间	稍后重试

网络优化建议（中国用户）：

# 测试到服务器的延迟
ping 服务地址

# 如果延迟超过 500ms，考虑：
# 1. 检查代理配置是否最优
# 2. 尝试不同时段使用（避开高峰）
# 3. 联系 QCode.cc 客服获取最优节点

上下文溢出 ¶

症状：

Claude 的回复开始「忘记」之前说过的话
回复质量明显下降
出现重复或矛盾的内容

解决方案：

# 方案 1：压缩上下文（保留关键信息）
/compact

# 方案 2：彻底清空（如果可以从头开始）
/clear

# 方案 3：精简每次输入
# 不要一次性发送大量文件内容
# 用 @ 引用代替粘贴
# 一次只处理一个任务

预防措施：

每完成一个独立任务后，考虑 /compact
换不同主题时，果断 /clear
使用 .claudeignore 排除不相关的大文件
用 @ 精准引用需要的文件，不要让 Claude 全局搜索

内存占用过高 ¶

症状：

系统变卡
Claude Code 进程占用大量内存

解决方案：

# 1. 检查 Node.js 内存使用
node -e "console.log(process.memoryUsage())"

# 2. 升级 Node.js 到最新 LTS 版本
nvm install 22
nvm use 22

# 3. 如果问题持续，限制 Node.js 最大内存
export NODE_OPTIONS="--max-old-space-size=4096"

# 4. 重启 Claude Code
# 退出当前会话，重新启动
exit
claude

常见错误码对照 ¶

错误码	含义	原因	解决方案
400	Bad Request	请求格式错误	检查输入是否包含非法字符；更新 Claude Code 到最新版
401	Unauthorized	API Key 无效或过期	检查 `ANTHROPIC_API_KEY` 设置；确认密钥未过期
403	Forbidden	没有权限	确认密钥有对应模型的访问权限
404	Not Found	模型或路径不存在	检查 `ANTHROPIC_BASE_URL` 和模型名称是否正确
429	Too Many Requests	请求过于频繁	等待 30-60 秒后重试；减少并发请求数
500	Internal Server Error	服务端内部错误	稍后重试；如持续出现，联系客服
502	Bad Gateway	上游服务不可用	稍后重试；检查是否有服务公告
503	Service Unavailable	服务暂时过载	等待几分钟后重试
529	API Overloaded	Claude API 过载	这是 Anthropic 服务端负载过高；等待后重试

429 详解：速率限制 ¶

429 是最常遇到的错误，值得详细说明：

触发原因：

请求频率过高：每秒发送请求过多
Token 消耗过快：短时间内消耗大量 token
并发会话过多：同时开了多个 Claude Code 实例
账户配额用完：当日/当月额度已耗尽

分级处理：

# 偶尔出现 429
# → 等待 30 秒自动重试，Claude Code 内置了重试逻辑

# 频繁出现 429
# → 减少请求频率
# → 使用 /compact 减少上下文大小
# → 避免同时运行多个 Claude Code 实例

# 持续 429
# → 检查套餐配额是否用完
# → 登录 QCode.cc Dashboard 查看使用量
# → 考虑升级套餐

529 详解：API 过载 ¶

529 是 Anthropic 特有的错误码，表示 Claude API 服务端过载：

Error: 529 API Overloaded
The API is temporarily overloaded. Please try again later.

应对措施：

这不是你的问题，是 Anthropic 服务端的临时状况
通常持续几分钟到几十分钟
等待 1-2 分钟后重试
如果持续出现，可以暂时切换到其他模型（如 GPT 系列）
关注 Anthropic Status 了解服务状态

其他常见问题 ¶

Claude Code 启动后没有反应 ¶

# 1. 检查是否正确安装
which claude
npm list -g @anthropic-ai/claude-code

# 2. 查看详细错误信息
claude --debug

# 3. 尝试清除缓存后重启
rm -rf ~/.claude/cache
claude

CLAUDE.md 不生效 ¶

# 1. 确认文件位置正确
ls -la CLAUDE.md                # 项目根目录
ls -la .claude/CLAUDE.md        # 项目私有配置
ls -la ~/.claude/CLAUDE.md      # 全局配置

# 2. 确认文件编码为 UTF-8
file CLAUDE.md
# 应该显示：CLAUDE.md: UTF-8 Unicode text

# 3. 确认没有语法错误（虽然是 Markdown，但某些特殊字符可能导致解析问题）
# 避免在 CLAUDE.md 中使用 ``` 以外的特殊标记

# 4. 重启 Claude Code 让配置生效
# 退出并重新进入

中文显示乱码 ¶

# 1. 检查终端编码设置
echo $LANG
# 应该包含 UTF-8，例如 en_US.UTF-8 或 zh_CN.UTF-8

# 2. 设置正确的编码
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

# 3. 确认终端支持 UTF-8
# macOS Terminal / iTerm2 默认支持
# Windows Terminal 默认支持
# Windows CMD 需要执行：chcp 65001

Git 冲突导致 Claude 操作失败 ¶

# 1. 先解决 Git 冲突
git status     # 查看冲突文件
git diff       # 查看冲突内容

# 2. 让 Claude 帮你解决冲突
> "查看当前的 git 冲突文件，帮我解决这些冲突。保留两边的修改。"

# 3. 解决后继续
git add .
git commit -m "resolve merge conflicts"

Docker 相关问题（高级用户）¶

如果你在 Docker 容器中使用 Claude Code：

# 确保容器内有 Node.js 22+
docker run -it node:22-slim bash

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 传入必要的环境变量
docker run -it \
  -e ANTHROPIC_API_KEY="cr_你的密钥" \
  -e ANTHROPIC_BASE_URL="https://你的服务地址" \
  -v $(pwd):/workspace \
  -w /workspace \
  node:22-slim claude

排查流程总结 ¶

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

1. 快速自检
   ├── claude --version（版本是否最新）
   ├── claude /doctor（自动诊断）
   └── node --version（Node.js ≥ 18）

2. 网络连通性
   ├── curl 测试 API 地址
   ├── 检查代理/VPN 设置
   └── 检查 DNS 解析

3. 认证配置
   ├── ANTHROPIC_API_KEY 格式是否正确
   ├── ANTHROPIC_BASE_URL 是否正确
   └── 密钥是否过期

4. 权限检查
   ├── 文件系统权限
   ├── Git 权限
   └── Claude Code 权限配置

5. 性能优化
   ├── /compact 压缩上下文
   ├── /model 切换合适的模型
   └── .claudeignore 排除大文件

6. 如果以上都无法解决 → 获取帮助