故障排除
修复 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 凭据 |
故障排除安装和登录 |
| 设置未应用、hooks 未触发、MCP 服务器未加载 | 调试您的配置 |
| 会话以自动模式启动，或 Claude 编辑文件并运行命令而不询问 | 会话启动的模式 |
API Error: 5xx、529 Overloaded、429、请求验证错误 |
错误参考 |
model not found 或 you may not have access to it |
错误参考 |
| VS Code 扩展未连接或未检测到 Claude | VS Code 集成 |
VS Code 或 SDK 应用中出现 Claude Code process exited with code 1 |
错误参考 |
| JetBrains 插件或 IDE 未检测到 | JetBrains 集成 |
| 高 CPU 或内存、响应缓慢、挂起、搜索找不到文件 | 性能和稳定性下方 |
如果您不确定哪个适用，请在 Claude Code 内运行 /doctor 以自动检查您的安装、设置、扩展和上下文使用情况；它会提议可以在您确认后应用的修复。如果 claude 根本无法启动，请从您的 shell 运行 claude doctor。运行 /mcp 以检查 MCP 服务器状态。
性能和稳定性
这些部分涵盖与资源使用、响应性和搜索行为相关的问题。
高 CPU 或内存使用
Claude Code 设计用于大多数开发环境，但在处理大型代码库时可能消耗大量资源。如果您遇到性能问题：
- 定期使用
/compact以减少上下文大小。如果它返回Not enough messages to compact.，则对话的轮次太少而无法总结；即使上下文已满，单个大粘贴填充它时也可能发生这种情况 - 在主要任务之间关闭并重启 Claude Code
- 考虑将大型构建目录添加到您的
.gitignore文件 - 使用
claude --safe-mode重启以检查插件、MCP 服务器或 hook 是否是源头。它禁用会话的所有自定义；如果使用量下降，请参阅调试您的配置以找出是哪一个
如果内存使用在这些步骤后仍然很高，请运行 /heapdump 以将两个文件写入 ~/Desktop：一个名为 <session-id>.heapsnapshot 的 JavaScript 堆快照和一个名为 <session-id>-diagnostics.json 的内存分解。Claude Code 从命令菜单中隐藏该命令；请完整输入它。在没有 Desktop 文件夹的 Linux 上，文件被写入您的主目录。
该命令还在对话中打印摘要，显示驻留集大小、JS 堆、数组缓冲区和未计算的本机内存，以及它检测到的任何泄漏指示器，例如高内存增长率或异常高的打开句柄数。摘要说明大部分内存是在 JS 堆中（快照捕获）还是在本机内存中（它不捕获）。
对输出执行以下两项操作之一：
- 报告它：打开 GitHub 问题并仅附加
-diagnostics.json文件，该文件包含打印摘要背后的统计信息，不包含任何对话内容或凭证 - 自己调查它：如果摘要说大部分内存是 JS 堆，请在 Chrome DevTools 中的 Memory → Load 下打开
.heapsnapshot文件，并按保留大小排序以查看什么在保留内存
如果摘要说大部分内存是本机内存，快照无法显示它；请在您的报告中包含摘要的泄漏指示器。
大型表格在终端中被截断
超过 200 行的 Markdown 表格呈现其前 200 行，后跟 … N more rows not shown 行。仅显示被限制：完整表格保留在对话中，/copy 复制每一行。对于在终端中太大而无法读取的表格，请要求 Claude 将其写入文件。在 v2.1.208 之前，Claude Code 呈现每一行，因此恢复包含非常大表格的会话可能会在重新呈现时停滞。
自动压缩停止并出现抖动错误
如果您看到 Autocompact is thrashing: the context refilled to the limit...，自动压缩成功，但文件或工具输出立即多次将上下文窗口重新填充到限制。Claude Code 停止重试以避免在没有取得进展的循环上浪费 API 调用。
要恢复：
- 要求 Claude 以较小的块读取超大文件，例如特定行范围或函数，而不是整个文件
- 运行
/compact，重点是删除大输出，例如/compact keep only the plan and the diff - 将大文件工作移到 subagent，以便它在单独的上下文窗口中运行
- 如果早期对话不再需要，运行
/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 写入的其他设置，请参阅终端配置。
全屏渲染中鼠标滚轮一次滚动一行
在全屏渲染中，Claude Code 滚动对话本身，而不是将其留给您的终端。如果每个滚轮缺口移动的行数少于您想要的，请运行 /scroll-speed 以提高每个缺口的行数并保存它，或设置 CLAUDE_CODE_SCROLL_SPEED 环境变量，除了在 JetBrains IDE 终端中，Claude Code 应用其自己的滚动处理，两者都不起作用。有关每个接受的值，请参阅鼠标滚轮滚动。
要在不改变速度的情况下移动得更快，请按 PgUp 和 PgDn 一次滚动半屏。要将滚动交还给您的终端的本机滚回，请运行 /tui default 以切换到经典渲染器。
沙箱内的剪贴板命令（如 `pbcopy`）失败
当沙箱打开时，剪贴板实用程序（如 pbcopy、xclip 和 wl-copy）可能无法从沙箱化 Bash 命令内部到达系统剪贴板，在 Claude 将文本管道到它们后保持您的剪贴板不变。
要将 Claude 的输出放在您的剪贴板上，请要求 Claude 在其响应中打印内容，然后运行 /copy。/copy 从 Claude Code 进程本身而不是从沙箱化命令写入剪贴板，因此沙箱不会阻止它。它可以复制单个代码块而不是整个响应，它还将复制的内容写入文件并打印路径，这在剪贴板写入无法到达您的终端时提供回退，例如通过 SSH。
要让管道命令直接到达剪贴板，请将 pbcopy *、wl-copy * 或 xclip * 添加到 excludedCommands，以便命令在沙箱外运行。
搜索和发现问题
如果搜索工具、@file 提及、自定义代理或自定义 skills 找不到文件，捆绑的 ripgrep 二进制文件可能无法在您的系统上运行。安装您平台的 ripgrep 包并告诉 Claude Code 改用它：
brew install ripgrep
sudo apt install ripgrep
apk add ripgrep
ripgrep 在 Alpine 的社区存储库中。如果 apk 报告包缺失，请参阅 Alpine Linux 设置。
pacman -S ripgrep
winget install BurntSushi.ripgrep.MSVC
然后在您的 shell 环境中或在您的 settings.json 的 env 块中将 USE_BUILTIN_RIPGREP 设置为 0：
{
"env": {
"USE_BUILTIN_RIPGREP": "0"
}
}
要确认切换生效，请在您的终端中运行 claude doctor 并检查搜索行显示您的系统 ripgrep 的路径而不是 OK (bundled)。
WSL 上的搜索速度缓慢或结果不完整
在 WSL 上跨文件系统工作时的磁盘读取性能损失可能导致使用 Claude Code 在 WSL 上时搜索匹配数少于预期。搜索仍然有效，但返回的结果少于本机文件系统。
解决方案：
-
提交更具体的搜索：通过指定目录或文件类型来减少搜索的文件数："在 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 可以内置访问其文档。
如有账户、账单或订阅问题，请改为联系 Anthropic 支持：登录 claude.ai（Console 用户：platform.claude.com），点击左下角的您的首字母缩写，然后选择获取帮助。请参阅如何获取支持了解完整流程，包括每个计划中谁可以联系人工代理。