33. 故障排查与常见问题

本节目标：学会排查 Claude Code 的安装、认证、网络、性能和配置问题，掌握 /doctor、/debug 等诊断工具的使用，附带国内使用提示和高频 FAQ。

用 Claude Code 跑着跑着突然报错，是挺让人抓狂的。好消息是，大部分问题都有固定的排查路径。这一章把常见的安装、认证、网络、性能、配置问题集中讲清楚，你在遇到报错时可以直接对照查找解决方案。

先跑诊断：/doctor

遇到问题别急着猜，先让 Claude Code 自己检查一遍。

在 Claude Code 内运行 /doctor，它会自动检查安装健康度、设置文件、扩展、上下文使用情况，并给出修复建议。如果 claude 根本无法启动，在 shell 里运行：

claude doctor

这会打印只读的安装和设置诊断信息，不启动会话。

其他诊断命令：

命令	作用
`/context`	查看上下文窗口里加载了什么
`/memory`	查看加载了哪些 CLAUDE.md 和规则文件
`/hooks`	查看活跃的 hook 配置
`/mcp`	查看 MCP 服务器连接状态
`/permissions`	查看当前生效的权限规则
`/status`	查看活跃的设置源
`/debug [issue]`	启用调试日志，让 Claude 帮你诊断

安装问题

command not found: claude

安装成功但运行 claude 时报 command not found 或 is not recognized，说明安装目录不在 PATH 里。

Claude Code 安装在 ~/.local/bin/claude（macOS/Linux）或 %USERPROFILE%\.local\bin\claude.exe（Windows）。

# macOS/Linux (Zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
claude --version

Windows PowerShell：

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

改完后重启终端。

安装脚本返回 HTML 或 403

bash: line 1: syntax error near unexpected token '<'
bash: line 1: `<!DOCTYPE html>'

这说明安装 URL 返回了 HTML 页面而不是安装脚本。常见原因：

区域不可用：如果 HTML 页面显示 “App unavailable in region”，Claude Code 在你的国家/地区不可用
企业防火墙或代理：阻止了对 downloads.claude.ai 的访问
网络问题：临时服务中断或路由问题

Tip

在国内遇到这个问题，可以用 Homebrew（macOS）替代安装，或者使用 npm 安装。如果只是网络问题，设置代理后重试。

TLS 或 SSL 连接错误

TLS connect error
unable to get local issuer certificate

更新系统的 CA 证书，或检查是否配置了 HTTPS_PROXY。企业环境可能有自签名证书，需要配置企业 CA 证书。

多个安装冲突

多个 Claude Code 安装会导致版本不匹配或意外行为。检查有哪些安装：

# macOS/Linux
which -a claude

# Windows
where.exe claude

只保留一个。推荐使用 ~/.local/bin/claude 的本机安装，删除其他的：

# 卸载 npm 全局安装
npm uninstall -g @anthropic-ai/claude-code

# 删除旧版本本地安装
rm -rf ~/.claude/local

认证问题

登录失败或登录循环

当登录失败且原因不明时，先试试干净的重新认证：

运行 /logout 完全注销
关闭 Claude Code
用 claude 重启并重新登录

如果浏览器不自动打开，按 c 复制 OAuth URL 到剪贴板，手动在浏览器中打开。

OAuth 错误：无效代码

OAuth error: Invalid code. Please make sure the full code was copied

登录代码过期或被截断。按 Enter 重试，浏览器打开后快速完成登录。

登录后 403 Forbidden

API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}

Pro/Max 用户：在 claude.ai/settings 确认订阅是否有效
Console 用户：确认账户有”Claude Code”或”Developer”角色
代理环境：企业代理可能干扰 API 请求

组织已被禁用

API Error: 400 ... "This organization has been disabled"

通常是旧的 ANTHROPIC_API_KEY 环境变量覆盖了订阅凭证。检查 shell 配置文件并删除：

unset ANTHROPIC_API_KEY
claude

检查 ~/.zshrc、~/.bashrc、~/.profile 中的 export ANTHROPIC_API_KEY=... 行并删除。

WSL2/SSH/容器中登录失败

在 WSL2、SSH 或容器中运行时，浏览器可能在不同主机上打开，重定向无法到达本地回调服务器。登录后浏览器会显示登录代码，把代码粘贴到终端即可。

如果浏览器根本不从 WSL2 打开：

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

或者用 claude auth login 从标准输入读取代码：

claude auth login

令牌过期

如果经常被要求重新登录，检查系统时钟是否准确—令牌验证依赖正确的时间戳。

macOS 上 Keychain 锁定也会导致登录失败：

# 解锁 Keychain
security unlock-keychain ~/Library/Keychains/login.keychain-db

网络问题

代理配置

在企业代理后面，安装前设置代理变量：

# macOS/Linux
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

检查网络连通性

curl -sI https://downloads.claude.ai/claude-code-releases/latest

HTTP/2 200 表示能连上服务器。如果看不到输出或超时，网络正在阻止连接。

性能问题

高 CPU 或内存使用

定期用 /compact 减少上下文大小
主要任务之间关闭并重启 Claude Code
把大型构建目录加到 .gitignore
用 claude --safe-mode 重启，检查插件、MCP 或 hook 是否是源头

如果内存使用仍然很高，运行 /heapdump 生成内存快照：

Warning

.heapsnapshot 文件包含进程中的每个字符串，不要分享或附加到公开 issue。报告内存问题时只分享 -diagnostics.json 文件，它只包含内存统计，不含对话内容或凭证。

自动压缩抖动

Autocompact is thrashing: the context refilled to the limit...

自动压缩成功了，但文件或工具输出立即又把上下文填满。恢复方法：

让 Claude 分块读取大文件，而不是整个读取
运行 /compact keep only the plan and the diff 保留重点
把大文件操作移到子代理
不需要早期对话就运行 /clear

命令挂起或冻结

按 Ctrl+C 尝试取消
不行就关闭终端重启

重启不丢对话，在同目录运行 claude --resume 继续。

终端文字乱码

VS Code、Cursor 等集成终端里字符显示为方框或乱码，是 GPU 渲染器的问题。运行 /terminal-setup 关闭 GPU 加速，或手动设置 terminal.integrated.gpuAcceleration 为 "off"。

搜索找不到文件

如果搜索工具、@file 提及找不到文件，可能是内置的 ripgrep 不兼容。安装系统级的 ripgrep：

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

然后设置环境变量 USE_BUILTIN_RIPGREP=0。

配置不生效

设置未应用

设置在托管、用户、项目、本地范围内合并，优先级从高到低。当设置不生效时，通常是被另一个范围覆盖了。

运行 /status 查看哪些设置源是活跃的，运行 /doctor 检查配置问题。

常见原因：

症状	原因
全局权限/hooks 被忽略	配置写到了 `~/.claude.json` 而非 `~/.claude/settings.json`
`settings.json` 值被忽略	`settings.local.json` 覆盖了 `settings.json`
Hook 永远不触发	matcher 拼写错误或用了数组而非字符串
Skill 没出现	文件放在了 `.claude/skills/name.md` 而非 `.claude/skills/name/SKILL.md`
MCP 服务器不加载	配置写到了 `.claude/` 下而非仓库根目录的 `.mcp.json`

Hook 不触发

运行 /hooks 查看活跃的 hook。如果 hook 没出现，说明没被读取—hooks 必须在 settings.json 的 "hooks" 键下定义，不是独立文件。

如果 hook 出现了但不触发，检查 matcher：

matcher 是字符串不是数组，用 | 匹配多个工具："Edit|Write"
工具名称区分大小写：Bash、Edit、Write，不是 bash、edit
拼写错误会导致无声失败

用 claude --debug hooks 启动并触发工具调用，可以实时看到 hook 评估日志。

MCP 服务器不加载

运行 /mcp 查看每个服务器的连接状态。常见问题：

项目级服务器需要一次性批准：从 /mcp 批准
启动失败：command 或 args 中的相对路径是常见原因，用绝对路径
连接但零工具：选择”重新连接”，还不行就运行 claude --debug mcp 看 stderr 输出

用安全模式排查

claude --safe-mode

安全模式禁用所有自定义（CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令和代理），但认证、模型、内置工具和权限正常工作。如果问题在安全模式下消失，说明是某个自定义配置导致的。

更彻底的排查—用空配置目录：

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

这会跳过 ~/.claude 下的所有内容。如果问题消失，原因就在你的配置文件里，逐个重新引入来定位。

国内使用提示

区域不可用怎么办

Claude Code 官方有地区限制。如果你所在区域不可用，有几个思路：

使用 Anthropic API Key：在 Claude Console 注册，获取 API Key，通过环境变量配置
使用第三方兼容 API：国内的 DeepSeek、通义千问、GLM 等提供 Anthropic 兼容接口（社区/第三方方案，非官方推荐）
使用 Coding Plan 服务：火山方舟、讯飞星辰、阿里云百炼等提供包月套餐，兼容 Claude Code（社区/第三方方案，非官方推荐）

Warning

下面提到的第三方 API 和 Coding Plan 都属于社区/第三方方案，非 Anthropic 官方推荐。使用时你的代码和对话会经过第三方服务器，安全性、稳定性、合规性自行评估。

接入 DeepSeek

DeepSeek 提供 Anthropic 兼容接口（社区/第三方方案，非官方推荐），通过环境变量配置：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=你的DeepSeek_API_Key
export ANTHROPIC_MODEL=deepseek-v4-pro
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-v4-flash

配置后直接运行 claude 即可使用，无需修改 Claude Code 源码。

跳过登录验证

如果你用第三方 API，不想走 OAuth 登录流程，可以手动编辑配置文件跳过：

macOS/Linux：~/.claude.json
Windows：C:\Users\你的用户名\.claude.json

{
  "hasCompletedOnboarding": true
}

保存后重启终端再运行 claude，不会再弹出登录窗口。

Note

使用第三方 API 时，ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 必须同时设置。如果只设了 Base URL 没设 Token，会报认证错误。

Coding Plan 方案

国内多家厂商推出了 Coding Plan 包月服务，支持 Claude Code（社区/第三方方案，非官方推荐）：

火山方舟 Coding Plan：支持 Doubao、DeepSeek、GLM、Kimi、MiniMax 等，限时优惠 9.9 元/月起（首两个月 2.5 折，第三个月起恢复原价）
讯飞星辰 MaaS（Astron Coding Plan）：首购 3.9 元/月起，续费 19 元/月，支持 DeepSeek、Qwen、GLM 等
阿里云百炼 Token Plan：支持 Qwen、DeepSeek、Kimi、GLM、MiniMax 等，个人版 39 元/月起

这些服务都提供 Anthropic 兼容接口，配置方式和 DeepSeek 类似，设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 即可。

FAQ 速查

Q：Claude Code 支持哪些操作系统？ macOS、Linux、Windows（需要 Git for Windows 提供的 bash 或 PowerShell）。不支持 32 位 Windows。

Q：需要联网才能用吗？ 是的，Claude Code 需要调用 API，必须联网。离线无法工作。

Q：VS Code 扩展和 CLI 是一回事吗？ VS Code 扩展内部捆绑了 CLI 副本，但不会添加到 PATH。要从终端使用 claude，需要单独安装 CLI。

Q：一个 API Key 能多台机器用吗？ 可以，API Key 没有机器绑定。订阅计划的 OAuth 认证也可以在多台机器上登录。

Q：升级后恢复会话很慢？ 升级后恢复会话会重新处理整个对话历史（因为系统提示变了，缓存失效）。会话越长，第一个请求越慢越贵。这是正常行为。

Q：/clear 和 /compact 有什么区别？ /clear 完全清空上下文，从零开始。/compact 压缩对话历史为摘要，保留关键信息但释放上下文空间。/compact 会破坏缓存，/clear 也会。

Q：为什么 Claude 忽略了我的 CLAUDE.md 指令？ 先运行 /memory 确认文件已加载。如果已加载但不遵守，可能是指令太模糊、与其他文件矛盾、或文件太长导致单条规则关注度下降。参考”编写有效的指令”部分优化。

Q：子代理（Subagent）忽略 CLAUDE.md？ 内置的 Explore 和 Plan 代理会跳过 CLAUDE.md。在委派提示中重新陈述关键指令。自定义子代理正常加载 CLAUDE.md。

获取更多帮助

如果以上都没解决你的问题：

运行 /doctor 和 /mcp 做全面检查
在 Claude Code 中用 /feedback 直接向 Anthropic 报告
查看 GitHub Issues 上的已知问题
不想折腾命令行的，可以下载 Claude Code Desktop 桌面应用，通过图形界面使用

小结

故障排查的核心思路就是”排除法”：先用 /doctor 自动检查，再用 /context、/memory、/hooks、/mcp 逐个确认配置是否加载，最后用 --safe-mode 或空配置目录排除自定义配置的影响。国内用户如果区域不可用，可以选 Anthropic API Key 或第三方兼容方案（DeepSeek、各家 Coding Plan 等，均属社区/第三方方案，非官方推荐），配置方式统一：设好 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 就行。