English ← MyDocs

文档索引

获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

故障排除

修复 Claude Code 中的高 CPU 或内存使用率、挂起、自动压缩抖动和搜索问题，并找到其他问题的对应页面。

本页涵盖 Claude Code 运行后的性能、稳定性和搜索问题。对于其他问题，请从与您遇到的困难匹配的页面开始：

症状跳转到
command not found、安装失败、PATH 问题、EACCES、TLS 错误排查安装和登录问题
登录循环、OAuth 错误、403 Forbidden、"organization disabled"、Bedrock/Vertex/Foundry 凭据排查安装和登录问题
设置未生效、钩子未触发、MCP 服务器未加载调试您的配置
API Error: 5xx、529 Overloaded、429、请求验证错误错误参考
model not found 或 you may not have access to it错误参考
VS Code 扩展未连接或未检测到 ClaudeVS Code 集成
JetBrains 插件或 IDE 未检测到JetBrains 集成
高 CPU 或内存、响应缓慢、挂起、搜索未找到文件下方性能和稳定性

如果不确定哪个适用，请在 Claude Code 内运行 /doctor 对您的安装、设置、MCP 服务器和上下文使用进行自动检查。如果 claude 完全无法启动，请从 shell 运行 claude doctor。

性能和稳定性

这些部分涵盖与资源使用、响应性和搜索行为相关的问题。

高 CPU 或内存使用率

Claude Code 设计为与大多数开发环境配合工作，但在处理大型代码库时可能会消耗大量资源。如果您遇到性能问题：

  1. 定期使用 /compact 减少上下文大小
  2. 在主要任务之间关闭并重启 Claude Code
  3. 考虑将大型构建目录添加到 .gitignore 文件中

如果执行这些步骤后内存使用率仍然很高，请运行 /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 调用。

恢复方法：

  1. 要求 Claude 以更小的块读取超大文件，例如特定行范围或函数，而不是整个文件
  2. 使用 /compact 并指定丢弃大型输出的重点，例如 /compact keep only the plan and the diff
  3. 将大文件工作移至子代理，使其在单独的上下文窗口中运行
  4. 如果之前的对话不再需要，运行 /clear

命令挂起或冻结

如果 Claude Code 似乎无响应：

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

重启不会丢失您的对话。在同一目录中运行 claude --resume 即可恢复会话。

搜索和发现问题

如果搜索工具、@file 提及、自定义代理或自定义技能找不到文件，内置的 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 上跨文件系统工作时的磁盘读取性能损失可能导致在 WSL 上使用 Claude Code 时匹配结果少于预期。搜索仍然有效，但返回的结果比原生文件系统少。

Note

在此情况下 /doctor 会显示搜索为正常。

解决方案：

  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 而非通过 WSL，以获得更好的文件系统性能。

获取更多帮助

如果您遇到此处未涵盖的问题：

  1. 运行 /doctor 一次性检查安装健康状况、设置有效性、MCP 配置和上下文使用情况
  2. 在 Claude Code 中使用 /feedback 命令直接向 Anthropic 报告问题
  3. 查看 GitHub 仓库了解已知问题
  4. 直接向 Claude 询问其功能和特性。Claude 内置了对其文档的访问权限。