11.4 故障排查实战

性能问题排查

CPU/内存占用高

如果 Claude Code 运行变慢或卡顿：

• 运行 /compact 压缩上下文，释放内存
• 关闭当前会话，开启新会话处理下一个任务
• 将大型构建目录（如 node_modules/、dist/）加入 .gitignore

生成内存快照供分析：

/heapdump

Claude Code 会生成 .heapsnapshot 文件，可在 Chrome DevTools 中打开分析。

自动压缩抖动（Autocompact Thrashing）

如果自动压缩反复失败，出现 "Autocompact is thrashing" 提示：

• 用更精确的行号引用（如 @filename#100-200）代替整文件读取
• 将大文件工作交给子代理处理
• 用 /clear 清除会话，从头开始

搜索问题

Search / Grep 找不到文件

确保已安装 ripgrep（Claude Code 用于代码搜索的底层工具）：

brew install ripgrep        # macOS
sudo apt install ripgrep    # Ubuntu/Debian
sudo apk add ripgrep        # Alpine Linux
winget install BurntSushi.ripgrep.Discovery  # Windows

如果已安装但仍有问题，可使用内置搜索：

export USE_BUILTIN_RIPGREP=0   # 强制使用 ripgrep
export USE_BUILTIN_RIPGREP=1   # 强制使用内置搜索

WSL 文件读取性能差

WSL 中访问 Windows 文件系统（/mnt/c/）有性能惩罚。解决方法：

• 将项目放在 WSL 文件系统内（~/projects/）
• 使用更精确的搜索关键词减少搜索范围
• 考虑在 WSL 内直接开发，而非跨文件系统

调试模式

遇到问题时，启用调试模式获取详细日志：

# 全量调试
claude --debug

# 过滤特定类别
claude --debug "api,hooks"

# 输出到指定文件
claude --debug-file /tmp/claude-debug.log

自动化诊断

在 Claude Code 中运行诊断命令：

/doctor

自动检查：安装状态、配置文件、MCP 服务器、上下文使用情况。

常见错误与解决方案

WSL / 容器环境特殊问题

WSL 中 Claude Code 无法启动

# 如果终端中 claude 命令无响应
claude doctor   # 从普通 shell 运行（不在 Claude Code 内）

# 如果 doctor 也无响应，可能是 WSL 环境问题
# 尝试在 PowerShell 中运行 Windows 版 Claude Code

登录码粘贴失效

在容器中无法完成 OAuth 回调时：

1. 运行 claude login
2. 浏览器打开登录页面后，按 c 复制登录码
3. 将登录码粘贴回终端

故障排查 Checklist

1. 运行 /doctor 检查基本状态
2. 检查网络和代理设置
3. 运行 claude --version 确认版本
4. 尝试 /logout 再 /login
5. 检查 ~/.claude/settings.json 配置是否正确
6. 尝试更新到最新版本 claude update