Claude Code 深度学习手册

主题

排错（Troubleshooting） ​

Claude Code 运行起来之后的性能、稳定性、搜索三类问题的排查页，并为其他类别问题（安装/登录、配置、API 报错、IDE 集成）提供分诊跳转表。

对你意味着什么 ​

出怪问题时的第一反应（按你环境）：

症状先做
配置/技能/MCP 没生效/doctor（查安装、设置、MCP、技能预算）；按 f 把诊断发给 Claude
serena/figma 等连不上/mcp 看状态/认证；不行 /reload-plugins
CLAUDE.md/AGENTS.md 没进上下文/context + /memory 看到底加载了啥（记住 CC 不读 AGENTS.md，要 @AGENTS.md）
卡住/跑飞Esc 中断；真死了关终端重开 claude --resume（同目录）
高 CPU/内存/heapdump（写到 home，你容器里无 Desktop）
搜索找不到文件内置 ripgrep；必要时装系统 rg 并 USE_BUILTIN_RIPGREP=0

安装/登录类问题见「安装登录排错」节；配置不生效深查见「调试配置」节。本页只管性能与稳定性。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

这是官方 Troubleshooting 页面，定位明确：只覆盖"Claude Code 已能跑起来之后"的 Performance and stability 问题，其余问题用分诊表引向专页。

怎么工作 ​

  • 分诊表（顶部）按症状路由：command not found/装失败/PATH/EACCES/TLS errors → troubleshoot-install；登录循环/OAuth/403 Forbidden/'organization disabled'/Bedrock·Vertex·Foundry 凭据 → troubleshoot-install#login-and-authentication；设置不生效/hooks 不触发/MCP servers 不加载 → debug-your-config；API Error: 5xx/529 Overloaded/429/请求校验错误 → errors；model not found 或 you may not have access to it → errors#theres-an-issue-with-the-selected-model；VS Code 扩展连不上/检测不到 → vs-code#fix-common-issues；JetBrains 插件/IDE 检测不到 → jetbrains#troubleshooting；高 CPU/内存·慢·卡死·搜索找不到 → 本页 Performance and stability。
  • 诊断兜底：拿不准用哪条时，在 Claude Code 内跑 /doctor，它一次性检查 installation、settings、MCP servers、context usage；如果 claude 根本起不来，改在 shell 里跑 claude doctor。
  • 高 CPU/内存机制：处理大型代码库时资源消耗大。三步缓解——/compact 缩小 context、在大任务之间关闭并重启 Claude Code、把大的 build 目录加进 .gitignore。仍居高不下时跑 /heapdump，它把一份 JavaScript heap snapshot 和一份内存明细写到 ~/Desktop（Linux 上若没有 Desktop 目录则写到 home 目录）。
  • 内存明细包含 resident set size、JS heap、array buffers、unaccounted native memory 四项，用来判断增长来自 JavaScript 对象还是 native 代码；要看 retainers 就在 Chrome DevTools 的 Memory → Load 里打开 .heapsnapshot 文件。报告内存问题时把两个文件都附到 GitHub issue。
  • auto-compact thrashing 机制：看到 Autocompact is thrashing: the context refilled to the limit... 说明自动 compaction 成功了，但某个文件或工具输出立刻把 context window 连续填满了好几次；Claude Code 主动停止重试，避免在不前进的循环里浪费 API 调用。
  • thrashing 恢复四步：让 Claude 分块读超大文件（指定行范围或某个函数，而非整文件）；用带焦点的 /compact 丢掉大输出，例如 /compact keep only the plan and the diff；把大文件相关工作丢给 subagent 在独立 context window 里跑；若早前对话已无用就 /clear。
  • 卡死/无响应机制：先按 Ctrl+C 尝试取消当前操作；若仍无响应只能关掉终端重启。重启不会丢失对话——在同一目录下跑 claude --resume 即可恢复 session。
  • 搜索机制：Search 工具、@file mentions、custom agents、custom skills 找不到文件，通常是内置的 ripgrep binary 在你的系统上跑不起来；装系统自带的 ripgrep 包，再设 USE_BUILTIN_RIPGREP=0 让 Claude Code 改用系统版。
  • WSL 搜索不全机制：跨文件系统读盘有性能惩罚，导致在 WSL 上搜索返回的匹配比预期少（搜索仍工作，只是结果偏少）。注意此情况下 /doctor 仍显示 Search 为 OK，所以不能只看 /doctor 判断。

怎么配置 / 用法 ​

诊断命令：/doctor（在 Claude Code 内运行，一次检查 installation/settings/MCP servers/context usage）；claude doctor（claude 起不来时在 shell 运行）。内存：/heapdump（输出到 ~/Desktop，Linux 无 Desktop 则写 home 目录，产物含 .heapsnapshot）。Context：/compact、/compact keep only the plan and the diff、/clear。恢复 session：claude --resume（同一目录）。 安装 ripgrep（按平台）：macOS brew install ripgrep；Ubuntu/Debian sudo apt install ripgrep；Alpine apk add ripgrep；Arch pacman -S ripgrep；Windows winget install BurntSushi.ripgrep.MSVC。安装后设环境变量 USE_BUILTIN_RIPGREP=0。 反馈/求助：/feedback（页内直接报告给 Anthropic）；GitHub issues：https://github.com/anthropics/claude-code/issues 。

什么时候用 ​

  • 当 Claude Code 已经能启动、但出现高 CPU/内存、响应慢、卡死、或搜索找不到文件时，用本页。
  • 拿不准问题归类时，先跑 /doctor（或 claude 起不来时 claude doctor）做自动检查。
  • 内存持续偏高、需要给 Anthropic 提 issue 取证时，用 /heapdump 生成快照。
  • 看到 thrashing 报错、或单个超大文件反复撑爆 context 时，用分块读 + 带焦点 /compact + subagent。
  • 在 WSL 上搜索结果偏少时，用更具体的搜索 / 迁移到 Linux 文件系统 / 改用原生 Windows。
  • 别用本页处理：装不上、登录失败、403、配置不生效、hooks/MCP 不加载、API 5xx/429/529、model not found、VS Code/JetBrains 集成问题——这些各有专页（见分诊表）。

限制 / 坑 ​

  • 本页只覆盖 Performance and stability（性能/稳定/搜索），安装·登录·配置·API 报错·IDE 集成都不在本页，需走分诊表跳转到专页。
  • auto-compact thrashing 时 Claude Code 会主动停止重试（不会自动死磕），需要用户手动按四步恢复。
  • 卡死且 Ctrl+C 无效时没有更优雅的办法，只能关终端重启（但对话不丢，可 claude --resume）。
  • claude --resume 恢复 session 必须在同一目录下运行。
  • 内置 ripgrep binary 可能在某些系统跑不起来，导致 Search / @file / custom agents / custom skills 全部找不到文件。
  • WSL 跨文件系统（/mnt/c/）搜索会因读盘性能惩罚返回偏少结果，且 /doctor 在这种情况下仍显示 Search 为 OK，不能据此判断搜索正常。
  • /heapdump 在 Linux 上若没有 Desktop 目录会把文件写到 home 目录，而非 ~/Desktop。

硬事实速查（19 条） ​

  • 兜底诊断：/doctor 在 Claude Code 内运行；claude doctor 在 claude 起不来时于 shell 运行。/doctor 检查 installation、settings、MCP servers、context usage 四项。
  • 高 CPU/内存三步：/compact 缩 context；大任务之间关闭并重启；把大 build 目录加入 .gitignore。
  • /heapdump 写一份 JavaScript heap snapshot + 内存明细到 ~/Desktop；Linux 无 Desktop 目录则写到 home 目录。
  • 内存明细四项：resident set size、JS heap、array buffers、unaccounted native memory。
  • 查看 retainers：在 Chrome DevTools 的 Memory → Load 打开 .heapsnapshot 文件。
  • 报告内存问题把两个文件都附到 https://github.com/anthropics/claude-code/issues 。
  • thrashing 报错原文：Autocompact is thrashing: the context refilled to the limit...，含义：自动 compaction 成功但文件/工具输出连续多次立刻填满 context window，于是停止重试以省 API 调用。
  • thrashing 恢复：分块读大文件（指定行范围/函数）；/compact keep only the plan and the diff（带焦点丢大输出）；把大文件工作交给 subagent 独立 context；不需要旧对话则 /clear。
  • 卡死处理：先 Ctrl+C 取消当前操作；无效则关终端重启。
  • 重启不丢对话：同一目录下 claude --resume 恢复 session。
  • 搜索找不到文件（Search 工具 / @file mentions / custom agents / custom skills）多因内置 ripgrep binary 跑不起来。
  • ripgrep 安装命令：macOS brew install ripgrep；Ubuntu/Debian sudo apt install ripgrep；Alpine apk add ripgrep；Arch pacman -S ripgrep；Windows winget install BurntSushi.ripgrep.MSVC。
  • 装完系统 ripgrep 后设环境变量 USE_BUILTIN_RIPGREP=0（详见 env-vars 页）。
  • WSL 搜索：跨文件系统读盘性能惩罚 → 匹配结果比原生文件系统少；搜索仍工作但结果偏少。
  • WSL 关键坑：此情况下 /doctor 仍显示 Search 为 OK。
  • WSL 三个解法：搜索更具体（指定目录/文件类型，如 'Search for JWT validation logic in the auth-service package'、'Find use of md5 hash in JS files'）；把项目放到 Linux 文件系统 /home/ 而非 Windows 文件系统 /mnt/c/；或直接在原生 Windows 上跑而非 WSL。
  • 分诊表跳转目标页：troubleshoot-install、troubleshoot-install#login-and-authentication、debug-your-config、errors、errors#theres-an-issue-with-the-selected-model、vs-code#fix-common-issues、jetbrains#troubleshooting。
  • 分诊触发字样举例：command not found、EACCES、TLS errors、403 Forbidden、'organization disabled'、Bedrock/Vertex/Foundry、API Error: 5xx、529 Overloaded、429、model not found、you may not have access to it。
  • 求助渠道：/feedback（页内直接报告给 Anthropic）、GitHub repo（查 known issues）、直接问 Claude（Claude 内置可访问自身文档）。

官方出处：https://code.claude.com/docs/en/troubleshooting