結論先說
- 進不去交互介面時在系統終端敲
claude doctor,進得去時直接敲/doctor:它能在幾秒內把安裝方式、多版本路徑衝突、自動更新狀態、ripgrep搜尋組件和配置文件語法過一遍篩子。 - 「升級後版本沒變」九成靠它破案:
doctor會直接打出當前實際運行的二進制絕對路徑,幫你抓出「以前用 npm 裝了一份殘留,遮擋了新裝的原生版本」。 - 覺得模型變笨或不守規矩時,跑
/doctor prompt-audit:它會全面掃描你的CLAUDE.md、規則目錄、技能與子代理定義,找出互相沖突的指令和早已刪除的幽靈文件路徑。 prompt-audit預設絕對安全:只出體檢報告與修改建議,在你明確點頭確認之前,不會擅自改寫任何一份本地或倉庫文件。

圖:本站根據 Claude Code 官方文檔 Troubleshooting 與 Memory 整理的示意圖
本文根據 Claude Code 官方文檔《Troubleshooting》《How Claude remembers your project》整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。
適用於誰
- 搜「claude doctor 怎麼用」「claude code 自檢」「doctor prompt-audit」的開發者;
- 明明跑了更新命令卻還是舊版本、配了 JSON 權限卻不攔截、或者某個 MCP 服務悄悄斷連找不到日誌的人;
- 團隊倉庫裏的
CLAUDE.md和.claude/rules/攢了大半年,感覺模型越來越「不聽話」,想一次性揪出過期或自相矛盾條款的人。
如果你遇到的是明確的登入 403 或網絡報錯碼,也可以對照彙總篇 /guides/claude-code-common-errors;本文專門講官方內置的兩把系統級聽診器怎麼用。
一、常規自檢(claude doctor / /doctor)重點看哪四行輸出
在項目根目錄打開終端直接運行 claude doctor(或在會話內輸入 /doctor),不要只看頂部的綠色對勾,排障時重點核對下面四個模組:
1. 安裝來源與可執行文件路徑(Installation & PATH)
很多老用戶早期用 npm install -g 裝過舊版,後來又用官方推薦的原生腳本裝了新版(升級渠道差異見 /guides/claude-code-changelog-release-notes-how-to-check)。如果系統 PATH 裏舊的 npm 全局目錄排在 ~/.local/bin 前面,你每次敲 claude 啟動的其實一直是半年前的舊殼子。看一眼 doctor 打印出的當前路徑與告警,刪掉多餘殘留副本即可根治。
2. 配置文件語法解析狀態(Settings Validation)
手改 ~/.claude/settings.json 或項目 .claude/settings.local.json 時,只要在最後一行多打了一個尾隨逗號(Trailing comma),整份配置可能就會解析失敗回退預設——表面上終端能正常聊天,但你配的 deny 安全規則全沒生效。/doctor 會直接標出哪一份 JSON 文件的哪一行格式非法。
3. 代碼檢索加速組件(Search / ripgrep)
在大倉庫裏如果發現 Claude 每次找函數都要卡十幾秒甚至漏結果,檢查 doctor 輸出裏的搜尋工具狀態:確認內置或系統級 rg(ripgrep)是否有可執行權限(在部分企業安全軟件攔截未知內嵌二進制的電腦上,可通過環境變量切換改用系統包管理器安裝的 rg)。
4. 已註冊 MCP 伺服器健康度
如果某個本地或遠程 MCP 工具突然消失(基礎配置見 /guides/claude-code-mcp-setup),運行 /doctor 配合 /mcp 可以快速定位是啟動命令找不到(比如切換了 Node 版本導致全局包路徑變了)還是握手超時。

圖:本站根據 Claude Code 官方文檔 Troubleshooting 整理的示意圖
二、進階利器:/doctor prompt-audit 給項目規則做大掃除
軟件項目迭代半年後,倉庫裏的指令文件往往會出現三種典型的「慢性腐化」(維護背景見 /guides/claude-md-auto-update-how-to-update):
- 幽靈路徑引用:三個月前把
src/legacy-auth/刪掉了,但CLAUDE.md裏還寫着「改鑑權前先讀src/legacy-auth/index.ts」,導致模型每次開局先白跑一次報錯讀取; - 跨文件規則打架:用戶全局
~/.claude/CLAUDE.md寫着「所有腳本預設用pnpm」,項目.claude/rules/ci.md寫着「必須統一用yarn」,兩條指令同時拼進上下文讓模型左右為難; - 針對舊代模型寫的過時補丁:以前為了哄早期弱模型寫的冗長死板格式限制,反而束縛了新模型的工具規劃能力。
在目標倉庫啟動會話後直接輸入:
text
/doctor prompt-audit
Claude Code 會自動遍歷檢查 CLAUDE.md、CLAUDE.local.md、AGENTS.md 以及 .claude/ 和 ~/.claude/ 下的規則、技能、命令與子代理文件,生成一份結構化的診斷報告:逐條列出哪裏有衝突、哪個文件路徑已經不存在、哪段話過於含糊無法驗證,並給出精簡改寫草案。你審閱同意後,再讓它落盤提交 Git 即可。
平時保持乾淨精簡的指令底座,不僅能提升首次改碼準確率,還能省下每次會話白白加載廢話消耗的訂閱配額;個人或團隊核對官方 Claude Code 訂閱檔位說明時,也可參考 /chongzhi/claude-code。
常見問題
Q:向技術支援或社區提問題單時,怎麼安全提供環境資訊?
優先貼 claude doctor 輸出的版本號、操作系統、安裝類型與錯誤摘要(記得先檢查並抹掉內部私有域名或路徑中的敏感用戶名),比單純截一張對話框報錯圖定位快得多;遇到客戶端介面異常還可以在會話裏使用 /bug 按官方指引提交反饋。
Q:為什麼我敲 /doctor prompt-audit 提示子參數不識別?
該體檢子功能隨較新的 Claude Code 版本推出。如果提示不支持,先按 claude doctor 給出的安裝方式把客戶端升級到最新 latest 通道版本後再試。
相關教學
- /guides/claude-code-common-errors:Claude Code 常見報錯碼與連接異常排查彙總
- /guides/claude-md-auto-update-how-to-update:
CLAUDE.md維護更新與自動記憶區別 - /guides/claude-code-changelog-release-notes-how-to-check:查看更新記錄與不同安裝方式的升級命令
- /guides/claude-code-mcp-setup:Claude Code MCP 伺服器安裝與排錯
參考資料
- Claude Code 官方文檔:Troubleshooting — https://code.claude.com/docs/en/troubleshooting
- Claude Code 官方文檔:How Claude remembers your project — https://code.claude.com/docs/en/memory
0 條評論
還沒有評論,來搶沙發~