Claude Code 运行后卡顿、死机、自动压缩反复 thrashing，或者 Search、@file、技能、子代理找不到文件时，先按这里排查。优先用 /doctor 和 /heapdump 判断是上下文、文件搜索还是系统资源问题，再按终端、WSL、ripgrep 和会话恢复步骤处理。

Claude Code 故障排查：卡顿、死机、搜索失效怎么解决 #

本页覆盖 Claude Code 已经启动后的性能、稳定性和搜索问题。先看下面的症状表，能最快定位到对应文档。

如果不确定从哪开始，在 Claude Code 里运行 /doctor，它会自动检查安装、设置、MCP 服务器和上下文使用情况。若 claude 根本起不来，就在 shell 里运行 claude doctor。

性能和稳定性 #

下面这些问题都和资源占用、响应速度、搜索行为有关。

高 CPU 或高内存占用 #

Claude Code 可以在大多数开发环境里工作，但在处理大型代码库时会消耗不少资源。遇到性能问题时：

1. 经常使用 /compact，减小上下文大小
2. 在重要任务之间关闭并重启 Claude Code
3. 考虑把大型构建目录加入 .gitignore

如果执行完这些步骤后内存仍然很高，运行 /heapdump，它会把 JavaScript heap snapshot 和内存分解写到 ~/Desktop。在没有 Desktop 目录的 Linux 上，文件会写到 home 目录。

这个分解结果会显示 resident set size、JS heap、array buffers 和未解释的 native memory，方便判断增长是在 JavaScript 对象里，还是在 native 代码里。要查看 retainers，可以在 Chrome DevTools 的 Memory → Load 中打开 .heapsnapshot 文件。提交内存问题到 GitHub 时，把这两个文件一起附上。

自动压缩报 thrashing 错误怎么解决 #

如果看到 Autocompact is thrashing: the context refilled to the limit...，说明自动压缩已经成功，但某个文件或工具输出马上又把上下文窗口填满了，而且连续发生了几次。Claude Code 会停止重试，避免在没有进展的循环里浪费 API 调用。

恢复方式：

1. 让 Claude 分块读取超大的文件，不要一次读完整文件，例如按行范围或按函数读取
2. 手动运行 /compact，并限定保留内容，例如 /compact keep only the plan and the diff
3. 把大文件相关工作交给 子代理，让它在独立的上下文窗口里运行
4. 如果前面的对话已经不需要了，运行 /clear

Claude Code 卡死或冻结怎么处理 #

如果 Claude Code 没有响应：

1. 按 Ctrl+C，尝试取消当前操作
2. 如果仍然无响应，可能需要关闭终端并重新启动

重启不会丢失会话。在同一目录下运行 claude --resume，可以接回之前的会话。

Search 和发现文件不工作怎么解决 #

如果 Search 工具、@file 提及、custom agents 或 custom skills 找不到文件，可能是内置的 ripgrep 二进制在你的系统上跑不起来。先安装平台自带的 ripgrep 包，然后让 Claude Code 改用它：

brew install ripgrep

sudo apt install ripgrep

apk add ripgrep

pacman -S ripgrep

winget install BurntSushi.ripgrep.MSVC

然后在你的 环境 中设置 USE_BUILTIN_RIPGREP=0。

WSL 上搜索结果很慢或不完整 #

在 WSL 中跨文件系统工作时，磁盘读取性能会下降，这可能导致 Claude Code 搜索时返回的匹配结果比预期少。Search 仍然能用，但结果数量会少于原生文件系统。

这种情况下，/doctor 会把 Search 显示为 OK。

解决方案：

1. 提交更具体的搜索条件：缩小要搜索的文件范围，比如指定目录或文件类型。
   例如：Search for JWT validation logic in the auth-service package 或 Find use of md5 hash in JS files.
2. 把项目移到 Linux 文件系统：如果可以，把项目放在 Linux 文件系统（/home/）下，而不是 Windows 文件系统（/mnt/c/）下。
3. 直接用原生 Windows：如果条件允许，改为在 Windows 上原生运行 Claude Code，文件系统性能通常更好。

获取更多帮助 #

如果遇到这里没有覆盖的问题：

1. 在 Claude Code 里运行 /doctor，一次检查安装健康状况、设置有效性、MCP 配置和上下文使用情况
2. 用 Claude Code 内的 /feedback 命令直接向 Anthropic 报告问题
3. 查看 GitHub 仓库 里的已知问题
4. 直接问 Claude 它的能力和功能，Claude 可以访问自己的文档

常见问题 #

Claude Code 卡顿、CPU 占用高，先做什么 #

先运行 /compact 降低上下文大小，再重启 Claude Code。若还是高占用，检查是否正在处理大型代码库，必要时把大构建目录加入 .gitignore。

Claude Code Search 找不到文件怎么办 #

先确认系统里的 ripgrep 能正常运行，然后设置 USE_BUILTIN_RIPGREP=0。如果你在 WSL 上工作，再检查项目是否放在 /mnt/c/ 这类跨文件系统路径下；这类场景会让搜索结果变少。

Autocompact is thrashing 怎么恢复 #

把大文件改成分块读取，或者手动运行 /compact keep only the plan and the diff。如果当前对话不再需要，可以直接 /clear，把大上下文清掉。