MYAIGC

主题

故障排除指南 ​

本节介绍Claude Code常见问题的诊断方法和解决方案。

诊断命令 ​

/doctor ​

运行完整的系统诊断：

bash
claude /doctor

输出示例：

Claude Code 诊断报告

✓ Node.js: v20.10.0
✓ Git: 2.43.0
✓ Claude认证: 已登录
✓ MCP服务器: 3个已配置
  - github: ✓ 已连接
  - postgres: ✗ 连接失败
  - puppeteer: ✓ 已连接
⚠ API配额: 本月已使用80%

发现1个问题：
- postgres MCP服务器无法连接
  建议: 检查DATABASE_URL环境变量

查看日志 ​

bash
# 启用详细日志
CLAUDE_DEBUG=1 claude

# 保存日志
claude 2>&1 | tee claude-debug.log

常见问题 ​

问题1：安装失败 ​

症状：

npm ERR! EACCES permission denied

解决方案：

bash
# 方案1：使用sudo
sudo npm install -g @anthropic-ai/claude-code

# 方案2：修复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

问题2：认证失败 ​

症状：

Error: Authentication failed

解决方案：

bash
# 重新登录
claude logout
claude login

# 或使用API Key
export ANTHROPIC_API_KEY=your-api-key
claude

问题3：MCP服务器连接失败 ​

症状：

MCP server "github" failed to connect

诊断步骤：

bash
# 1. 启用MCP调试
claude --mcp-debug

# 2. 检查MCP配置
claude mcp get github

# 3. 检查环境变量
echo $GITHUB_TOKEN

# 4. 测试npx命令
npx @modelcontextprotocol/server-github

常见原因：

  • 环境变量未设置
  • API Token过期
  • 网络连接问题
  • npx缓存问题

解决方案：

bash
# 清除npx缓存
npx clear-npx-cache

# 重新配置MCP
claude mcp remove github
claude mcp add github

问题4：上下文溢出 ​

症状：

Context window exceeded

解决方案：

bash
# 压缩上下文
/compact

# 或清除会话
/clear

# 开始新会话
claude --new-session

问题5：命令执行超时 ​

症状：

Command timed out after 30s

解决方案：

bash
# 增加超时时间
export MCP_TIMEOUT=120
claude

# 或在配置中设置
claude config set timeout 120

问题6：文件权限错误 ​

症状：

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

解决方案：

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

# 修改权限
chmod 644 /path/to/file

# 或使用正确的用户运行

问题7：Token不足 ​

症状：

Rate limit exceeded

解决方案：

bash
# 检查使用情况
/cost

# 等待配额恢复
# 或升级订阅计划

问题8：Hooks不生效 ​

症状： Hooks配置后没有执行

诊断步骤：

bash
# 检查Hooks配置
claude /hooks

# 检查配置文件
cat .claude/settings.json | grep hooks

# 测试Hook命令
# 手动执行配置中的命令

常见原因：

  • JSON格式错误
  • 命令路径问题
  • 权限问题

解决方案：

bash
# 验证JSON格式
python -m json.tool .claude/settings.json

# 检查命令可执行
which prettier

# 添加调试输出
{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "echo 'Hook executed' >> /tmp/claude-hook.log && prettier --write \"$CLAUDE_FILE_PATHS\""
      }]
    }]
  }
}

问题9：Windows特定问题 ​

症状：

'claude' is not recognized as an internal or external command

解决方案：

powershell
# 检查PATH
$env:PATH

# 添加到PATH
$env:PATH += ";C:\Users\$env:USERNAME\AppData\Roaming\npm"

# 永久添加
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\$env:USERNAME\AppData\Roaming\npm", "User")

问题10：网络问题 ​

症状：

Network error
Connection refused

解决方案：

bash
# 检查网络连接
curl -I https://api.anthropic.com

# 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 配置代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# 或禁用代理
unset HTTP_PROXY HTTPS_PROXY

性能问题 ​

响应缓慢 ​

可能原因：

  • 网络延迟
  • 上下文过长
  • MCP服务器响应慢

解决方案：

bash
# 1. 压缩上下文
/compact

# 2. 检查MCP状态
claude --mcp-debug

# 3. 使用更快的模型
claude -m haiku

内存占用高 ​

解决方案：

bash
# 清除会话历史
rm -rf ~/.claude/sessions/*

# 重启Claude
claude --new-session

配置重置 ​

完全重置 ​

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

# 删除所有配置
rm -rf ~/.claude

# 重新登录
claude login

仅重置权限 ​

bash
# 编辑权限配置
# 删除 permissions 部分
vim ~/.claude/settings.json

获取帮助 ​

内置帮助 ​

bash
/help

查看文档 ​

bash
# 在浏览器中打开文档
claude docs

报告Bug ​

bash
/bug

# 或在GitHub提Issue
# https://github.com/anthropics/claude-code/issues

社区支持 ​

预防措施 ​

定期维护 ​

bash
# 更新Claude Code
npm update -g @anthropic-ai/claude-code

# 清理旧会话
rm -rf ~/.claude/sessions/old-*

# 检查配置
claude /doctor

备份配置 ​

bash
# 备份重要配置
cp ~/.claude/settings.json ~/.claude/settings.json.bak
cp .claude/settings.json .claude/settings.json.bak

监控使用 ​

bash
# 定期检查成本
/cost

# 设置预算提醒
claude config set budgetAlert 50  # 50美元时提醒

小结 ​

遇到问题时：

  1. 先运行 /doctor 诊断
  2. 启用调试模式查看详细日志
  3. 查看本文档的常见问题部分
  4. 必要时重置配置或重新安装