排障

Claude Code 运行起来后的性能、稳定性和搜索问题（高 CPU 或内存、卡死、自动压缩震荡、剪贴板、搜索失效），以及其他问题该去哪一页。

本页讲 Claude Code 运行起来之后的性能、稳定性和搜索问题。其他问题，先找和你卡住的地方对应的官方页面：

症状	去哪里
`command not found`、安装失败、PATH 问题、`EACCES`、TLS 错误	官方「Troubleshoot installation and login」
登录循环、OAuth 错误、`403 Forbidden`、「organization disabled」、Amazon Bedrock、Google Cloud 或 Microsoft Foundry 凭据	官方「Troubleshoot installation and login」的登录与认证一节
设置没生效、Hook 没触发、MCP 服务器没加载	官方「Debug your configuration」
Skill 不在 `/skills` 里、Claude 不自动用、改了不生效、云端会话找不到	Skill 的「排障」一节
会话以 auto 模式开始，或 Claude 不经询问就编辑文件和运行命令	权限与权限模式里的「会话以哪种模式开始」
`API Error: 5xx`、`529 Overloaded`、`429`、请求校验错误	官方「Error reference」
`model not found` 或 `you may not have access to it`	官方「Error reference」
VS Code 扩展不连接或检测不到 Claude	VS Code 的常见问题一节
JetBrains 插件或 IDE 检测不到	JetBrains 的排障一节
高 CPU 或内存、响应慢、卡死、搜索找不到文件	下面的「性能与稳定性」

如果你不确定适用哪一条，在 Claude Code 里运行 /doctor，对你的安装、设置、扩展和上下文用量做自动检查；它会提出可以在你确认后应用的修复。如果 claude 根本启动不了，改在 shell 里运行 claude doctor。

性能与稳定性

高 CPU 或内存占用

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

定期使用 /compact 减小上下文大小。如果它返回 Not enough messages to compact.，说明对话的回合太少，没法总结（即使上下文已满，也可能因为单次大粘贴把它填满）
在重大任务之间关闭并重启 Claude Code
考虑把大型构建目录加入你的 .gitignore 文件
用 claude --safe-mode 重启，检查插件、MCP 服务器或 Hook 是不是来源。它会为这个会话禁用所有自定义项；如果用量下降，见「Debug your configuration」

如果一个会话的堆内存超过 2.5GB，会出现严重内存使用警告。想释放内存，重启 Claude Code 并运行 claude --continue，在全新进程里恢复对话。在全屏渲染之外，运行 /compact 也能释放内存。内存使用回落到 2.5GB 以下后警告就消失了。

如果采取这些步骤后内存使用仍然很高，运行 /heapdump 往 ~/Desktop 写两个文件：一个名为 <session-id>.heapsnapshot 的 JavaScript 堆快照，和一个名为 <session-id>-diagnostics.json 的内存明细。

.heapsnapshot 文件包含进程里的每个字符串，包括你的完整对话和凭据。不要把它附到公开 issue 里或分享它。

报告它：开一个 GitHub issue，只附 -diagnostics.json 文件（它带有打印摘要背后的统计数据，不含对话内容或凭据）；自己调查：如果摘要说大部分内存是 JS 堆，在 Chrome DevTools 的 Memory → Load 里打开 .heapsnapshot 文件，按保留大小排序，看是什么占着内存。

终端里大表格被截断

超过 200 行的 Markdown 表格会渲染前 200 行，后面跟一行 … N more rows not shown。只有显示被限制：完整的表格仍留在对话里，/copy 会复制每一行。

自动压缩因「震荡」而停止

如果你看到 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。

全屏渲染下鼠标滚轮一次只滚一行

在全屏渲染里，Claude Code 自己滚动对话，而不是交给你的终端。如果每格滚轮移动的行数少于你想要的，运行 /scroll-speed 提高每格的行数并保存。想不改变速度而更快地移动，按 PgUp 和 PgDn 一次滚动半屏。想改用终端原生的回滚，运行 /tui default 切换到经典渲染器。

`pbcopy` 这类剪贴板命令在沙箱里失败

启用沙箱时，pbcopy、xclip、wl-copy 这类剪贴板工具在沙箱化的 Bash 命令里可能无法触达系统剪贴板，Claude 把文字通过管道传给它们后你的剪贴板保持不变。想把 Claude 的输出放到你的剪贴板上，让 Claude 把内容打印在回复里，然后运行 /copy：/copy 从 Claude Code 进程本身写剪贴板，而不是从沙箱化的命令，所以沙箱不会阻止它。

通过 SSH 时复制的文字到不了本地剪贴板

当 Claude Code 通过 SSH 在远程机器上运行时，它无法在你本地机器上运行剪贴板工具。在 tmux 之外，当你在全屏渲染里选择文字或运行 /copy 时，Claude Code 会把文字作为 OSC 52 转义序列发送到你的终端。有些终端不处理 OSC 52：iTerm2 会忽略它，直到你打开 Settings > General > Selection > Applications in terminal may access clipboard；macOS Terminal.app 不支持它。不用 OSC 52 获取文字的办法：拖动时按住终端的原生选择键，然后用终端通常的快捷键复制，如 Cmd+C（Terminal.app 里这个键是 Fn，iTerm2 里是 Option）；或在远程机器上设置 CLAUDE_CODE_DISABLE_MOUSE=1，让你的终端在整个会话里处理选择。

搜索与发现问题

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

brew install ripgrep      # macOS
sudo apt install ripgrep  # Debian/Ubuntu
apk add ripgrep           # Alpine
pacman -S ripgrep         # Arch

Windows 上用 winget install BurntSushi.ripgrep.MSVC。装好之后按官方原文的说明配置 Claude Code 使用系统的 ripgrep；WSL 上搜索缓慢或结果不完整的问题，官方原文也有专门一节。