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

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

---

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

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

---

## 一、快速诊断

### 运行 /doctor

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

```
/doctor
```

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

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

```bash
claude doctor
```

### 常见问题速查表

| 症状 | 解决方案 |
|------|---------|
| `command not found: claude` | 检查 PATH |
| 登录后 403 Forbidden | 检查账户权限 |
| 高 CPU/内存占用 | 压缩上下文、重启 |
| 命令卡住不动 | Ctrl+C 或重启终端 |
| MCP 服务器无法连接 | 检查配置和网络 |
| 搜索找不到文件 | 安装 ripgrep |
| 上下文自动压缩失败 | 减少大文件读取 |

---

## 二、安装问题

### 2.1 command not found

**症状**：

```bash
claude
# command not found: claude
# 或 Windows: 'claude' is not recognized
```

**原因**：Claude Code 未添加到 PATH。

**解决方案**：

```bash
# 检查安装位置
which claude  # macOS/Linux
where claude  # Windows

# 手动添加 PATH（macOS/Linux）
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Windows：添加到系统 PATH
# 控制面板 → 系统 → 高级系统设置 → 环境变量
```

### 2.2 安装脚本返回 HTML

**症状**：

```bash
curl -fsSL https://claude.ai/install.sh | sh
# syntax error near unexpected token '<'
```

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

**解决方案**：

```bash
# 方法一：使用备用安装方式
npm install -g @anthropic-ai/claude-code

# 方法二：直接下载二进制
# macOS
curl -Lo claude https://downloads.claude.ai/claude-code-releases/latest/claude-macos-x64
chmod +x claude
sudo mv claude /usr/local/bin/

# Linux
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 错误

**症状**：

```bash
# TLS connect error
# SSL/TLS secure channel error
# unable to get local issuer certificate
```

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

**解决方案**：

```bash
# macOS
brew install ca-certificates

# Ubuntu/Debian
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

**症状**：

```bash
# 安装过程中显示 Killed
```

**原因**：内存不足。

**解决方案**：

```bash
# 添加 swap 空间
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. 重置登录：

```bash
claude logout
claude login
```

### 3.2 OAuth 错误

**症状**：

```
OAuth error: Invalid code
```

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

**解决方案**：

```bash
# 清除登录状态
claude logout

# 重新登录
claude login

# 如果仍有问题，尝试浏览器登录
claude login --browser
```

### 3.3 WSL2 登录失败

**症状**：WSL2 中 OAuth 登录失败。

**解决方案**：

```bash
# 方法一：使用浏览器登录
claude login --browser

# 方法二：复制 Windows 上的登录信息
# 在 Windows 上登录成功后
# 复制 ~/.claude/ 目录到 WSL
cp -r /mnt/c/Users/YOUR_USER/.claude ~/.claude
```

### 3.4 企业认证失败

**症状**：

```
Could not load the default credentials
ChainedTokenCredential authentication failed
```

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

**解决方案**：

```bash
# 检查环境变量
echo $ANTHROPIC_API_KEY

# Bedrock
aws configure
export CLAUDE_CODE_USE_BEDROCK=1

# Vertex
gcloud auth application-default login
export CLAUDE_CODE_USE_VERTEX=1

# Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
```

---

## 四、性能问题

### 4.1 高 CPU 或内存占用

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

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

**解决方案**：

```bash
# 1. 压缩上下文
/compact

# 2. 检查上下文大小
/context

# 3. 清理会话
/clear

# 4. 重启 Claude Code
# Ctrl+D 或 exit，然后重新启动

# 5. 将大目录加入 .gitignore
echo "node_modules/\nbuild/\ndist/" >> .gitignore
```

**诊断内存问题**：

```bash
# 生成堆转储
/heapdump

# 文件会保存到 ~/Desktop/
# 用 Chrome DevTools 打开 .heapsnapshot 文件分析
```

### 4.2 自动压缩循环失败

**症状**：

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

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

**解决方案**：

```bash
# 1. 分段读取大文件
# 不要：读取整个文件
# 要：读取特定行范围

# 2. 使用子 Agent
# 子 Agent 有独立的上下文窗口

# 3. 手动压缩并丢弃大输出
/compact keep only the plan and the diff

# 4. 如果之前的对话不再需要
/clear
```

### 4.3 命令卡住不动

**症状**：Claude Code 无响应。

**解决方案**：

```bash
# 1. 尝试取消
Ctrl+C

# 2. 如果无响应，关闭终端并重启

# 3. 恢复会话
claude --resume
```

### 4.4 响应变慢

**症状**：Claude 响应越来越慢。

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

**解决方案**：

```bash
# 1. 检查上下文使用
/context

# 2. 超过 60% 就压缩
/compact

# 3. 检查是否有问题对话
# 删除重复、无关的对话

# 4. 使用子 Agent 隔离探索任务
```

---

## 五、搜索问题

### 5.1 搜索找不到文件

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

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

**解决方案**：

```bash
# 安装系统 ripgrep
# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# 告诉 Claude Code 使用系统 ripgrep
export USE_BUILTIN_RIPGREP=0
```

### 5.2 WSL 搜索结果不完整

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

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

**解决方案**：

```bash
# 方法一：更精确的搜索
# 不要：搜索所有文件
# 要：指定目录或文件类型

# 方法二：项目放在 Linux 文件系统
# 不要：/mnt/c/projects/
# 要：~/projects/
```

---

## 六、MCP 问题

### 6.1 MCP 服务器无法连接

**症状**：

```
MCP server "xxx" failed to connect
```

**解决方案**：

```bash
# 1. 查看服务器状态
/mcp

# 2. 查看详细日志
tail -f ~/.claude/logs/mcp.log

# 3. 重启服务器
/mcp restart xxx

# 4. 检查配置
cat .mcp.json
cat ~/.claude/.mcp.json

# 5. 检查命令是否存在
which npx
which uvx
```

### 6.2 MCP 工具调用超时

**症状**：

```
MCP tool call timed out
```

**解决方案**：

```bash
# 增加超时时间
export MCP_TIMEOUT=30000  # 30 秒

# 检查服务器日志
tail -f ~/.claude/logs/mcp.log
```

### 6.3 MCP 服务器认证失败

**症状**：

```
Authentication failed
API key invalid
```

**解决方案**：

```bash
# 1. 检查环境变量
echo $API_KEY

# 2. 检查配置文件中的变量引用
# .mcp.json 中应该用 ${API_KEY} 而不是明文

# 3. 验证 API Key
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/test
```

---

## 七、配置问题

### 7.1 配置不生效

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

**解决方案**：

```bash
# 1. 检查配置文件位置
# 项目级：.claude/settings.json
# 用户级：~/.claude/settings.json

# 2. 检查 JSON 语法
cat .claude/settings.json | python -m json.tool

# 3. 重启 Claude Code
# 配置在启动时加载

# 4. 检查优先级
# 项目级 > 用户级
```

### 7.2 Hooks 不触发

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

**解决方案**：

```bash
# 1. 检查配置
/hooks

# 2. 检查 JSON 语法
cat .claude/settings.json | python -m json.tool

# 3. 检查脚本权限
ls -la .claude/hooks/
chmod +x .claude/hooks/*.sh

# 4. 测试脚本
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | .claude/hooks/my-hook.sh
echo $?  # 应该返回 0
```

### 7.3 CLAUDE.md 规则被忽略

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

**解决方案**：

```bash
# 1. 检查文件位置
# 应该在项目根目录

# 2. 检查文件名
# 应该是 CLAUDE.md（大写）

# 3. 检查规则格式
# 用 <critical> 标签包裹重要规则

# 4. 压缩上下文后重试
/compact
```

---

## 八、API 错误

### 8.1 429 Too Many Requests

**症状**：

```
API Error: 429 Too Many Requests
```

**原因**：请求频率超限。

**解决方案**：

```bash
# 1. 等待几分钟

# 2. 减少并发请求
# 不要同时启动多个 Claude 实例

# 3. 升级到更高套餐
```

### 8.2 500/529 服务器错误

**症状**：

```
API Error: 500 Internal Server Error
API Error: 529 Overloaded
```

**原因**：服务器端问题。

**解决方案**：

```bash
# 1. 等待几分钟后重试

# 2. 检查服务状态
# https://status.anthropic.com/

# 3. 使用 --resume 恢复会话
claude --resume
```

### 8.3 模型不可用

**症状**：

```
model not found
you may not have access to it
```

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

**解决方案**：

```bash
# 1. 检查可用模型
# Pro: claude-sonnet-4-6, claude-opus-4-7
# Team/Enterprise: 额外模型

# 2. 使用可用模型
# 在对话中切换或修改配置
```

---

## 九、日志与调试

### 9.1 查看日志

```bash
# 日志位置
~/.claude/logs/

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

# 查看 MCP 日志
tail -f ~/.claude/logs/mcp.log

# 查看错误日志
grep -i error ~/.claude/logs/*.log
```

### 9.2 调试模式

```bash
# 启用详细日志
export CLAUDE_DEBUG=1

# 启用 MCP 调试
export MCP_DEBUG=1

# 启动 Claude Code
claude
```

### 9.3 检查环境

```bash
# 检查版本
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` |
| 看日志 | `tail -f ~/.claude/logs/` |
| 分层排查 | 安装 → 登录 → 配置 → 运行 |
| 逐步排除 | 一次改一个变量 |

**预防措施**：

| 措施 | 说明 |
|------|------|
| 定期压缩 | 上下文超 50% 就 `/compact` |
| 管理 .gitignore | 排除大目录 |
| 使用子 Agent | 隔离探索任务 |
| 保持更新 | `claude update` |

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

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

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

软件研发

开发工具

编程语言

后端

ClaudeCode错误排查指南提供全面解决方案，涵盖安装、登录、性能、搜索等常见问题。包含快速诊断命令/doctor、错误症状速查表、详细分步修复流程。重点解决403认证失败、高CPU占用、搜索异常、MCP连接问题等痛点，提供日志查看和调试技巧。适用于各平台用户快速定位和修复ClaudeCode使用中的各类技术问题。

文件系统

服务器

Windows

Ubuntu

Linux

OAuth

Agent

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Claude Code 错误排查指南：从症状到解决方案-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐