Claude Code 故障排查完整指南：高 CPU、卡死、自动压缩震荡和搜索失效

Claude Code 出问题时，不要盲目重装。官方 Troubleshooting 文档把问题分成几类：安装登录、配置、API 错误、IDE 集成、性能稳定性和搜索问题。本文聚焦 Claude Code 已经能运行后的性能和稳定性排查。

先用 /doctor 定位问题#

如果 Claude Code 能启动，在会话内运行：

/doctor

它会自动检查：

• 安装健康状态
• settings 配置
• MCP server 状态
• 上下文占用
• 搜索能力

如果 claude 根本启动不了，在 shell 里运行：

claude doctor

问题导航表#

高 CPU 或内存占用#

Claude Code 能处理大多数开发环境，但在大仓库或长会话中可能占用较多资源。

官方建议：

1. 定期运行 /compact
2. 大任务之间关闭并重启 Claude Code
3. 把大型构建目录加入 .gitignore

常见应该加入 .gitignore 的目录：

node_modules/
dist/
build/
.next/
.nuxt/
coverage/
.pytest_cache/
.venv/
target/

如果内存仍然很高，运行：

/heapdump

它会在 ~/Desktop 写出 JavaScript heap snapshot 和 memory breakdown。Linux 没有 Desktop 时，写到 home 目录。

memory breakdown 会显示：

• resident set size
• JS heap
• array buffers
• unaccounted native memory

.heapsnapshot 可用 Chrome DevTools 的 Memory → Load 打开，分析保留对象。

Auto Compact Thrashing 怎么办？#

错误类似：

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

意思是：自动压缩成功了，但某个文件或工具输出立刻又把上下文窗口填满，反复几次后 Claude Code 停止自动重试，避免浪费 API 调用。

解决方案：

1. 让 Claude 分块读取大文件#

不要说：

读取这个 5MB 日志并分析

改成：

只读取 error.log 中包含 "FATAL" 的行，或者读取 1200-1450 行之间的 stack trace

2. 用带目标的 /compact#

/compact keep only the plan and the diff

明确告诉 Claude 保留什么，丢弃无关的大输出。

3. 把大文件任务交给 Subagent#

把这个大日志分析任务交给 subagent，在独立上下文里完成，只把结论带回来

Subagent 有独立上下文窗口，不会污染主会话。

4. 如果历史不重要，直接 /clear#

/clear

适合任务已经完成、旧上下文没有价值的情况。

Claude Code 卡死或冻结#

处理顺序：

1. 按 Ctrl+C 尝试取消当前操作
2. 如果仍无响应，关闭终端并重启
3. 在同一目录运行恢复：

claude --resume

重启不会丢失对话，--resume 可以继续之前的 session。

搜索不到文件、@file 不工作、Skills/Agents 不发现#

如果 Search 工具、@file、custom agents 或 custom skills 找不到文件，可能是内置 ripgrep 在你的系统上无法运行。

安装系统版 ripgrep：

macOS：

brew install ripgrep

Ubuntu/Debian：

sudo apt install ripgrep

Alpine：

apk add ripgrep

Arch：

pacman -S ripgrep

Windows：

winget install BurntSushi.ripgrep.MSVC

然后设置：

export USE_BUILTIN_RIPGREP=0

这样 Claude Code 会使用系统安装的 ripgrep。

WSL 搜索慢或结果不完整#

如果项目位于 /mnt/c/ 这类 Windows 文件系统路径，WSL 的磁盘读性能会影响搜索，导致结果比原生文件系统少。

解决办法：

1. 更具体地搜索：限制目录和文件类型
2. 把项目移动到 Linux 文件系统，例如 /home/you/project
3. 改用原生 Windows Claude Code

示例 Prompt：

在 auth-service 包里搜索 JWT validation 逻辑，只看 TypeScript 文件

比：

搜索 JWT

更可靠。

实战排查流程#

情况 1：Claude 变慢#

/doctor
/context
/compact keep only current task plan and modified files

然后检查仓库是否有超大目录没被 ignore。

情况 2：自动压缩反复失败#

1. 找出最近读入的大文件/大输出
2. /compact keep only the plan and the diff
3. 后续让 Claude 分块读取
4. 大日志/大 JSON 交给 subagent

情况 3：搜索异常#

1. /doctor 看 Search 状态
2. 安装系统 ripgrep
3. 设置 USE_BUILTIN_RIPGREP=0
4. WSL 用户把项目移到 /home/

来源：Claude Code 官方文档 - Troubleshooting | 整理：ClaudeEagle