Troubleshooting 运行时问题排查

Claude Code 运行时的性能、稳定性和搜索问题排查。安装和登录问题见 troubleshoot-install，API 错误见 errors。

问题导航

症状	去哪里
`command not found`、安装失败、PATH 问题	troubleshoot-install
登录循环、OAuth 错误、403 Forbidden	troubleshoot-install
设置不生效、hooks 不触发、MCP 不加载	Debug your configuration
API Error: 5xx、529、429、请求验证错误	errors
高 CPU/内存、响应慢、挂起、搜索找不到文件	本文

快速诊断：运行 /doctor（会话内）或 claude doctor（shell 中）自动检查安装、设置、MCP 和上下文占用。

高 CPU 或内存使用

常规措施：

定期运行 /compact 减少上下文大小
在主要任务之间关闭并重启 Claude Code
将大型构建目录加入 .gitignore

内存诊断：运行 /heapdump 生成 JavaScript 堆快照和内存分解报告，保存到 ~/Desktop（Linux 无 Desktop 则保存到 home 目录）。用 Chrome DevTools → Memory → Load 打开 .heapsnapshot 文件分析 retainer。

自动压缩抖动（Thrashing）

症状：看到 Autocompact is thrashing: the context refilled to the limit...

原因：压缩成功但某个文件或工具输出立即重新填满上下文，多次循环后 Claude Code 停止重试。

恢复方法：

让 Claude 分块读取大文件（指定行范围或函数）
/compact keep only the plan and the diff（带焦点的压缩）
将大文件工作移到子 Agent（独立上下文窗口）
/clear 如果之前的对话不再需要

命令挂起或冻结

Ctrl+C 尝试取消当前操作
如果无响应，关闭终端并重启
重启后运行 claude --resume 恢复会话（不会丢失对话）

搜索和发现问题

症状：Search 工具、@file 引用、自定义 Agent 或 Skills 找不到文件。

原因：内置 ripgrep 二进制不兼容当前系统。

解决方案：安装系统 ripgrep 并设置 USE_BUILTIN_RIPGREP=0：

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

然后设置环境变量：

export USE_BUILTIN_RIPGREP=0

WSL 搜索结果不完整

原因：WSL 跨文件系统（Windows ↔ Linux）的磁盘读取性能损耗导致搜索结果少于预期。/doctor 在此情况下仍显示 Search OK。

解决方案：

提供更具体的搜索范围（指定目录或文件类型）
将项目移到 Linux 文件系统（/home/）而非 Windows 文件系统（/mnt/c/）
改用原生 Windows 运行 Claude Code

获取更多帮助

/doctor 一键检查安装健康、设置有效性、MCP 配置和上下文占用
/feedback 向 Anthropic 报告问题（附带会话记录）
查看 GitHub Issues
直接问 Claude（内置文档访问权限）

与其他概念的关联

troubleshoot-install — 安装和登录阶段的错误
errors — API 运行时错误参考
env-vars — USE_BUILTIN_RIPGREP 等环境变量

实践要点

高内存问题先用 /heapdump 收集数据再报告，附带两个文件（快照 + 分解报告）
压缩抖动通常是某个工具返回了超大结果，用 /context 找出是哪个工具
WSL 用户建议将项目放在 Linux 文件系统，性能差异显著

Wiki AI

目录