Claude Code 自动化与排错

性能与稳定性排查

2 分钟阅读

故障排查

修复 Claude Code 中的高 CPU 或内存占用、卡死、自动压缩抖动，以及搜索问题，并找到其他问题对应的正确页面。

本页涵盖 Claude Code 运行期间的性能、稳定性和搜索问题。对于其他问题，请从与你遇到的情况相匹配的页面开始：

症状	请前往
`command not found`、安装失败、PATH 问题、`EACCES`、TLS 错误	故障排查安装与登录
更新或安装下载失败，提示 `The connection dropped while downloading the update` 或 `aborted`	错误参考
登录循环、OAuth 错误、`403 Forbidden`、“organization disabled”、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭据问题	故障排查安装与登录
设置未生效、钩子未触发、MCP 服务器未加载	调试你的配置
`API Error: 5xx`、`529 Overloaded`、`429`、请求校验错误	错误参考
`model not found` 或 `you may not have access to it`	错误参考
VS Code 扩展无法连接或检测不到 Claude	VS Code 集成
JetBrains 插件或 IDE 未被检测到	JetBrains 集成
高 CPU 或内存占用、响应缓慢、卡死、搜索找不到文件	下方的性能与稳定性

如果你不确定该看哪一个，在 Claude Code 内运行 /doctor，它会自动检查你的安装、设置、扩展和上下文用量；在你确认后，它会提出可以应用的修复方案。如果 claude 完全无法启动，请改为在你的 shell 中运行 claude doctor。运行 /mcp 可以检查 MCP 服务器状态。

性能与稳定性

以下小节涵盖与资源用量、响应能力和搜索行为相关的问题。

高 CPU 或内存占用

Claude Code 设计上能兼容大多数开发环境，但在处理大型代码库时可能消耗大量资源。如果你遇到性能问题：

定期使用 /compact 缩减上下文大小
在主要任务之间关闭并重启 Claude Code
考虑把大型构建目录加入你的 .gitignore 文件
用 claude --safe-mode 重启，检查是否某个插件、MCP 服务器或钩子是问题来源。它会为该会话关闭所有自定义配置；如果用量下降，请参阅调试你的配置找出是哪一个

如果这些步骤之后内存用量仍然居高不下，运行 /heapdump，将一份 JavaScript 堆快照和内存细分写入 ~/Desktop。在没有 Desktop 文件夹的 Linux 上，这些文件会写入你的主目录。

这份细分展示了常驻集大小、JS 堆、数组缓冲区，以及未计入的原生内存，有助于判断增长发生在 JavaScript 对象中还是原生代码中。要检查引用持有者，在 Chrome DevTools 的 Memory → Load 下打开该 .heapsnapshot 文件。在GitHub报告内存问题时，请附上这两个文件。

自动压缩因抖动错误而停止

如果你看到 Autocompact is thrashing: the context refilled to the limit...，说明自动压缩成功了，但某个文件或工具输出连续多次立即重新填满了上下文窗口。Claude Code 会停止重试，以避免在一个没有进展的循环上浪费 API 调用。

要恢复：

让 Claude 分小块读取那个过大的文件，例如指定行范围或函数，而不是读取整个文件
用一个能去掉大量输出的焦点运行 /compact，例如 /compact keep only the plan and the diff
把处理大文件的工作转移到一个子智能体中，让它在一个独立的上下文窗口中运行
如果不再需要之前的对话，运行 /clear

命令卡死或冻结

如果 Claude Code 看起来没有响应：

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

重启不会丢失你的对话。在同一个目录中运行 claude --resume 即可继续之前的会话。

编辑器集成终端中出现乱码或损坏的文本

如果在 VS Code、Cursor 或 Devin Desktop 的集成终端中运行 Claude Code 时，字符渲染成方块、涂抹或错误的字形，很可能是该终端的 GPU 渲染器导致的。在 Claude Code 内运行 /terminal-setup，将 terminal.integrated.gpuAcceleration 设为 "off"，或在你编辑器的设置中手动设置它并重新加载窗口。关于 /terminal-setup 写入的其他设置，请参阅终端配置。

搜索与发现问题

如果搜索工具、@file 提及、自定义智能体或自定义技能找不到文件，可能是内置的 ripgrep 二进制文件在你的系统上无法运行。安装你平台对应的 ripgrep 软件包，并告诉 Claude Code 改用它：

macOS
Ubuntu/Debian
Alpine
Arch
Windows

brew install ripgrep

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

WSL 上搜索结果缓慢或不完整

在 WSL 上跨文件系统工作时的磁盘读取性能损耗，可能导致在 WSL 上使用 Claude Code 时匹配结果比预期更少。搜索仍能正常工作，但返回的结果比原生文件系统上更少。

在这种情况下，claude doctor 会显示 Search 为 OK。

解决方法：

提交更具体的搜索：通过指定目录或文件类型来减少要搜索的文件数量：“在 auth-service 软件包中搜索 JWT 校验逻辑”，或“在 JS 文件中查找 md5 哈希的使用”。
将项目移到 Linux 文件系统：如果可能，确保你的项目位于 Linux 文件系统（/home/）上，而不是 Windows 文件系统（/mnt/c/）上。
改用原生 Windows：考虑在 Windows 上原生运行 Claude Code，而不是通过 WSL，以获得更好的文件系统性能。

获取更多帮助

如果你遇到的问题本页未涵盖：

运行 /doctor 进行安装体检，运行 /mcp 检查 MCP 服务器状态
在 Claude Code 内使用 /feedback 命令直接向 Anthropic 报告问题
查看GitHub 仓库中的已知问题
直接向 Claude 询问它的能力和特性。Claude 内置了对其文档的访问权限。