出错怎么办：常见报错排雷大全

📍 Claude Code 干活

一个 IT 客服台和 FAQ 装订本，机器人客服坐在后面

这一篇的正确读法

这一篇不是从头读到尾的——它是「IT 帮助中心的 FAQ 速查」。

✅ 遇到报错 → Ctrl+F 搜你看到的关键词 → 跳到对应小节 → 抄修复
✅ 每个小节 = 症状(你看到的) + 原因(为什么) + 修复(直接抄一行命令)
✅ 看完就跑，不用记住所有

💡 拿不准是哪一类问题，先让它自己体检：在 Claude Code 里输入 /doctor，它会检查重复安装、PATH（系统找命令时会去翻的一串目录清单）、坏掉的设置文件等常见毛病，你确认后还能直接帮你修；claude 根本启动不了，就在终端里运行 claude doctor。

收藏这一篇到浏览器书签 / 桌面快捷方式，踩坑的那一刻就知道来哪查。

8 个最常见报错总览

8 宫格

序号	你看到的关键词	章节锚点
1	`command not found: claude` / `'claude' is not recognized`	跳到第 1 节
2	`Not logged in` / `401` / `Invalid API key`	跳到第 2 节
3	`Unable to connect to API` / `connection refused` / `ENOTFOUND`	跳到第 3 节
4	CPU 100% / 风扇狂转 / 卡顿 / 内存警告	跳到第 4 节
5	AI 改错了，我撤不回来	跳到第 5 节
6	`tool use` 卡住不动	跳到第 6 节
7	中文显示 `???` / 方框乱码	跳到第 7 节
8	`/clear` 也没用，怎么硬重启	跳到第 8 节
其他	额度用完 / `429` / `529 Overloaded` / `Context limit reached`	跳到「另外几种常见提示」

1. command not found: claude

症状

打开终端输入 claude，终端报下面其中一种（报错原文，按系统不同）：

系统	报错原文
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows 命令提示符（CMD）	`'claude' is not recognized as an internal or external command`
Windows PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

原因

Claude Code 装好了，但它所在的目录不在 PATH 里，你的终端还不知道 claude 这个命令在哪。官方原生安装把 claude 放在 ~/.local/bin/ 里（Windows 是用户文件夹下的 .local\bin\claude.exe），这个目录没进 PATH，终端就找不到它。

另一种情况：你只装了 VS Code 扩展。扩展自带一份自己用的 Claude Code，不会放进 PATH，终端里本来就没有 claude 命令，要按安装篇另外装一次命令行版。

修复

第一步：关掉终端，重新开一个，再输入 claude --version。刚装完时，旧窗口还不知道有这个新命令，重开最简单。

第二步：还不行，确认到底装上了没有。 原生安装的话，Mac / Linux 用完整路径运行一次：

~/.local/bin/claude --version

能显示版本号（比如 2.1.283 (Claude Code)），说明装好了，只差 PATH。Windows 在 PowerShell 里运行 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"，显示 True 就是装好了。

第三步：把 ~/.local/bin 加进 PATH。

Mac / Linux — 先看它在不在 PATH 里：

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

有输出（比如 /Users/you/.local/bin）说明已经在了；没输出就把它加进去（source 是让配置文件马上生效，也可以直接重开终端）。

Mac 默认的 shell（终端里负责执行命令的程序）是 zsh，用这两行：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux 默认的是 bash，用这两行：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Mac 上如果你用的是 bash，把这一行写进 ~/.bash_profile。

Windows（PowerShell） — 先看它在不在 PATH 里：

$env:PATH -split ';' | Select-String '\.local\\bin'

没输出就把它加进你的用户 PATH，然后关掉 PowerShell 重新打开：

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

用 npm 装的，claude 不在 ~/.local/bin，而在 npm 的全局目录里：运行 npm prefix -g 看位置（Mac / Linux 是它下面的 bin 子目录，Windows 就是这个目录本身），把那个目录加进 PATH，方法同上。

⚠️ 别急着用 npm 再装一遍。 原生安装找不到命令，几乎都是 PATH 的问题；再用 npm 装一份，电脑上就有两份 Claude Code，容易版本错乱。想看是不是已经装了好几份，Mac / Linux 运行 which -a claude，Windows 运行 where.exe claude：列出不止一个的话，官方建议只留一份（推荐原生版），多的按当初的安装方式卸掉，见文末「还不行：先体检，再按原来的方式重装」。

（安装步骤看 Claude Code 安装与首次配置）

2. Not logged in / 401 / Invalid API key

症状

启动 claude 或发出第一条消息后报错。现在的报错原文是这几种：

Not logged in · Please run /login
Invalid API key · Fix external API key
Please run /login · API Error: 401 Invalid authentication credentials

走 DeepSeek 这类第三方接口时，401 后面的文字是对方服务返回的说明。

原因

先分清你走的是哪条路——三条路用的「钥匙」（凭据）不一样：

你怎么用 Claude Code	用的凭据
Claude 订阅（Pro / Max / Team 等）	在 Claude Code 里用 `/login` 登录的账号
Anthropic API（Claude Console 里建的 Key）	环境变量 `ANTHROPIC_API_KEY`
DeepSeek 等第三方接口	环境变量 `ANTHROPIC_AUTH_TOKEN`，外加服务地址 `ANTHROPIC_BASE_URL`

常见原因：

登录过期或被登出
Key 错了（打字错了 / 复制粘贴丢字符 / 已经被撤销）
变量用错了：直连 Anthropic 的 Console Key 要放在 ANTHROPIC_API_KEY；ANTHROPIC_AUTH_TOKEN 是给 DeepSeek 这类第三方接口用的
终端里残留了一个旧的 ANTHROPIC_API_KEY：它被批准用过一次之后，会压过你的订阅登录
服务地址跟 Key 不是同一家（用的是 DeepSeek 的 Key，地址却还是 Anthropic 的，或者反过来）

修复

第一步（所有人）：看清现在用的是哪种凭据。 在 Claude Code 里输入：

/status

它会显示当前用的是登录账号还是 API Key。进不去会话的话，在终端运行 claude auth status。

走 Claude 订阅的：

运行 /login 重新登录。
/status 显示正在用 API Key、而你想用订阅：先清掉这个变量再登录。Mac / Linux 运行 unset ANTHROPIC_API_KEY，PowerShell 运行 Remove-Item Env:ANTHROPIC_API_KEY，然后 /login。如果这个变量是写在 ~/.zshrc 这类配置文件里的，要把那一行删掉，不然下次开终端它又回来了。

走 Anthropic API（Console Key）的：

确认 Key 没打错，也没在 Claude Console 里被撤销；
确认变量名是 ANTHROPIC_API_KEY，而且是在你启动 claude 的那个终端里设的。只想知道设没设、不想把 Key 打印到屏幕上，可以这样查：

[ -n "$ANTHROPIC_API_KEY" ] && echo 已设置 || echo 没设置

（PowerShell：if ($env:ANTHROPIC_API_KEY) { '已设置' } else { '没设置' }）

走 DeepSeek 的：

用同样的办法查 ANTHROPIC_AUTH_TOKEN 设没设（把上面命令里的变量名换掉），再确认 Key 来自 DeepSeek 开放平台、API 账户有余额；
确认服务地址是 DeepSeek 的：运行下面这行，应该显示 https://api.deepseek.com/anthropic。

echo $ANTHROPIC_BASE_URL

服务地址、Key、模型名那几个变量要一次设全，照下面那篇抄，别只设一两个。走 DeepSeek 时 /login 帮不上忙。

走 Anthropic 官方（订阅或 Console Key）就不要设 ANTHROPIC_BASE_URL，让它默认走 api.anthropic.com。

📚 详细配置看 Claude Code 接入 DeepSeek：配置与费用。

3. connection refused / ENOTFOUND

症状

启动 claude 或发消息后报：

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
fetch failed

（旧版本显示成 Unable to connect to API (ECONNREFUSED) 这类格式。）

原因

网络问题——你的电脑连不上模型服务器：

DNS（把域名翻译成网络地址的服务）出错 / 被 hosts 文件改坏
公司 / 学校的代理设置错了
你的网络限制了访问目标域名
设置里残留了一个 ANTHROPIC_BASE_URL，指向一个已经停掉的本地代理或网关
走 Anthropic 官方，但你在中国大陆：Anthropic 不向中国大陆提供服务，本来就连不上

修复

Step 1：用 curl 测一下能不能连到服务器（别用 ping：很多服务器本来就不回 ping，ping 不通说明不了问题）。按你走的是哪家，选对应的一行。

走 DeepSeek 的：

curl -I https://api.deepseek.com

走 Anthropic 官方的：

curl -I https://api.anthropic.com

Windows PowerShell 里要写成 curl.exe -I https://api.deepseek.com。

怎么看结果：第一行出现 HTTP/ 开头的状态行（后面跟一个数字），说明网络能连到那台服务器；数字是 403 的，可能是被代理拦了，或者所在地区不支持；报 Could not resolve host（找不到这个域名）、一直等到超时，或者连接被拒绝，才是网络本身不通。

Step 2：检查你设的服务地址（base URL）有没有打错字：

echo $ANTHROPIC_BASE_URL

（PowerShell 里是 echo $env:ANTHROPIC_BASE_URL。）走 DeepSeek 的应该是：https://api.deepseek.com/anthropic（注意是 .com 不是 .cn）。走 Anthropic 官方的，这里应该是空的；如果残留着一个旧地址，把它从 ~/.zshrc 这类配置文件和 Claude Code 的设置文件里删掉，再开一个新终端。

Step 3：国内常见情况——如果你没设 ANTHROPIC_BASE_URL，它默认走 api.anthropic.com，在中国大陆连不上。修复：不要只补一个地址，照 Claude Code 接入 DeepSeek 一次设全服务地址、DeepSeek 的 Key 和模型名那几个变量。只改地址的话，要么还是报认证错误，要么请求仍按默认的 Opus 5.5 模型名发过去，被 DeepSeek 当成 deepseek-v4-pro、按贵得多的 Pro 价计费；电脑上存着 claude.ai 登录的，登录凭据还会被一起发到那个地址。

4. CPU 100% / 风扇狂转 / 卡顿

症状

跟 Claude Code 聊一会，电脑风扇开始狂转，CPU 飙到 100%，整个系统卡顿，或者弹出内存占用过高的警告。

原因

处理大项目时，Claude Code 本身就可能占不少 CPU 和内存：会话开得越久、读进来的东西越多，占用越高。装的插件、MCP 服务器（外部工具连接器）或 hook（钩子：在固定时机自动运行的脚本）出问题，也会拖慢。

（压缩对话是 Claude Code 把旧对话发给模型、在服务器上生成摘要，不在你电脑上算；新版遇到「刚压缩完又被塞满」会报 Autocompact is thrashing 并停止重试，不会无限空转。）

修复

应急：

/clear

（清空当前上下文，从零开始；旧对话还能用 /resume 找回）

或者：连按两次 Ctrl+C 退出，再运行 claude --continue，在新进程里接着刚才的对话。

官方建议的排查顺序：

定期 /compact 给上下文瘦身（提示 Not enough messages to compact 的话，说明对话轮数太少，没什么可总结的）
大任务之间，关掉 Claude Code 重开，需要时用 claude --continue 接上
把大的构建目录（比如 dist、build）加进 .gitignore（git 的忽略清单）
用 claude --safe-mode 启动一次：它会临时关掉 CLAUDE.md、插件、MCP、hooks 等所有自定义配置。占用降下来了，说明是某个插件、MCP 或 hook 在捣乱

内存警告：一个会话的内存超过 2.5GB，会弹出严重内存警告，照上面第 2 条重开再 claude --continue 就行。还是偏高、想报问题，可以输入 /heapdump，它会在桌面生成两个诊断文件：报问题时只附带名字以 -diagnostics.json 结尾的那个；另一个 .heapsnapshot 文件里有你的完整对话和凭据，别发给任何人。

长期习惯：

别在一个会话里堆超过 3 小时的对话
别一次让它读 10+ 个大文件(分批读)
CLAUDE.md 控制在 200 行以内

📚 详细机制看上下文窗口怎么算的。

5. AI 改错了，我撤不回来

症状

Claude Code 「热心」地帮你重构了一堆文件，结果方向不对。你没 git commit,git reset 不敢用(怕误伤其他改动)。

原因

你忘了 Claude Code 有 checkpoint 这个功能。

修复

在 Claude Code 内输入：

/rewind

(或者连按两下 Esc)会打开回滚菜单，列出这段对话的历史节点。挑一个改之前的时刻，选「恢复代码」，回车——那之后的文件改动全部撤销。

📚 详细用法看checkpoint 一键回滚。

⚠️ 关键提醒：checkpoint 在 Claude Code 关掉后仍然保留（恢复会话后还能 /rewind），但只存在本机、默认约 30 天后清理；而且它只管 Claude 用编辑工具直接改的文件，命令（比如 rm）的后果、子智能体改的文件都撤不回。回滚完立刻 git add + git commit 钉到 git 历史里。

6. tool use 卡住不动

症状

Claude Code 显示：

⏺ Running tool: Read
   |
   v
   (这里就不动了,等 5 分钟也没反应)

原因

最常见 3 种：

Read 一个超大文件(单文件超过几 MB)
Bash 跑了一个等不到结束的命令：比如启动了一个后台常驻程序（daemon）、tail -f，或者卡在 read 等你输入
网络请求超时(curl / wget 在等一个挂掉的服务器)

修复

第一步：按 Esc 中断当前动作——这是 Claude Code 的「刹车键」，中断后会话还在，可以继续对话。

如果 Esc 按了没反应，退出整个程序：连按两次 Ctrl+C(会话不会丢，重开后 claude --continue 就能接上)。

如果还没反应，关掉这个终端窗口，开一个新终端，回到同一个项目目录运行 claude --continue 接上。窗口关不掉，或者 Claude Code 放在 tmux 这类「关掉窗口也照样运行」的工具里，就按第 8 节只结束卡住的那一个进程。

⚠️ 别用 pkill -f claude 这类按名字批量杀的命令：你同时开着的其他 Claude Code 会话会被一起杀掉。

长期对策:

让它读文件前先告诉它「这个文件可能很大，你扫前 200 行就够」
跑 Bash 命令前看一眼是不是会一直跑、不会自己结束的命令（避免 tail -f、watch）
给 curl 加超时：curl -m 10 ...（最多等 10 秒）

7. 中文显示 ??? / 方框乱码

症状

Claude 输出中文时显示：

???????
□□□□□□□

或者你输入中文它返回时全是乱码。

原因

终端的字符编码没设成 UTF-8；显示成方框（□）的，多半是字体里没有中文字。

修复

Windows(命令提示符 / PowerShell):

chcp 65001

(每次开终端跑一遍，或者写进 PowerShell profile)

想一劳永逸：在 Windows 的区域设置里找到「Beta: 使用 Unicode UTF-8 提供全球语言支持」，勾上后重启电脑（这个开关会影响整台电脑的所有程序）。

Mac / Linux — 检查 locale（系统的语言和编码设置）：

locale

如果 LANG 不是 *.UTF-8(比如是 C 或者 POSIX)，改：

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

写到 ~/.zshrc 永久生效。

显示成方框（□）：把终端字体换成支持中文的（比如微软雅黑，或者带中文的等宽字体）。Windows Terminal 本身就能显示 UTF-8，它的设置里也没有「文本编码」这一项，不用去找。

在 VS Code、Cursor 这类编辑器的内置终端里出现方块、错字或花屏：在 Claude Code 里运行 /terminal-setup，它会关掉编辑器终端的 GPU 加速；也可以自己在编辑器设置里把 terminal.integrated.gpuAcceleration 改成 off，再重新加载窗口。

8. /clear 也没用，怎么硬重启

症状

Claude Code 整个进程卡死,/clear / Ctrl+C / Esc Esc Esc 全都没反应，界面定格。

原因

进程真的卡死了——可能是内存占用太高、网络请求卡住，或者它启动的某个命令（子进程）挂住了。

修复

第一步：关掉这个终端窗口，开一个新终端，回到同一个项目目录，运行：

claude --continue

它会接上这个目录里最近的一次对话（想从列表里挑别的对话，用 claude --resume）。重启不会丢对话。

第二步：窗口关不掉，或者关了进程还在（比如放在 tmux 这类「关掉窗口也照样运行」的工具里），就只结束卡住的那一个进程。

Mac / Linux — 另开一个终端，先列出命令里带 claude 的进程。

Mac 用这行：

pgrep -fl claude

Linux 用这行：

pgrep -fa claude

每行开头的数字是进程编号（PID），后面是启动命令。找到命令开头就是 claude 的那一行（只开了一个 Claude Code 的话就是它；开了好几个，按启动时带的参数分辨，分不清就先在其他还能用的会话里输入 /exit 退出，剩下的就是卡住的那个），结束它（12345 换成你看到的编号）：

kill 12345

等几秒还在，再用 kill -9 12345 强制结束。然后照第一步 claude --continue 接上。

Windows — 只开了一个 Claude Code、也没开 Claude 桌面应用的话，在任务管理器里结束 claude.exe 就行。不然先在 PowerShell 里列出每个 claude 进程的编号（Id）、启动时间和程序位置，再只结束卡住的那个：

Get-Process claude | Select-Object Id, StartTime, Path

Claude 桌面应用的进程也叫 claude.exe，它的程序位置（Path）里带 WindowsApps 或 AnthropicClaude，别动它；命令行版原生安装的在 .local\bin 下面，npm 装的在 npm 的目录里。开了好几个会话，按启动时间（StartTime）找卡住的那个。

找到以后，结束它（12345 换成你看到的 Id）：

Stop-Process -Id 12345

⚠️ 别用「一锅端」的办法：

网上旧教程里「把所有 node 进程都杀掉」那一招别再用了：现在的 Claude Code 是原生程序，不是 node 进程（上面列出来的命令就是 claude，Windows 是 claude.exe），杀 node 根本杀不到它，反而会把你电脑上正在跑的本地网页服务、用 npx 启动的 MCP 服务器这些 Node.js 程序一起杀掉。
pkill -f claude 会把你同时开着的所有 Claude Code 会话一起结束；Get-Process claude | Stop-Process -Force 也一样，还可能连 Claude 桌面应用一起关掉（它的程序名也叫 Claude）。

长期对策:

内存占用高 → 大任务之间重开 Claude Code，用 claude --continue 接上（见第 4 节）
网络卡 → 用第 3 节的 curl -I 查一下，或者重启路由器试试
频繁出现 → 升级到最新版：
- 原生安装会在后台自动更新；想马上更新，运行 claude update
- Homebrew 装的：brew upgrade claude-code
- WinGet 装的：winget upgrade Anthropic.ClaudeCode
- npm 装的：npm install -g @anthropic-ai/claude-code@latest（别用 npm update -g，它可能升不到最新版）

另外几种常见提示

上面 8 节之外，这几种也很常见（报错原文方便 Ctrl+F）：

你看到的	意思	怎么办
`You've hit your session limit · resets 3:45pm`（或 `weekly limit`）	Claude 订阅的额度用完了（按 5 小时和每周两层计算；Ultra 账户通过官方验证以后只有每周这一层）	等到提示的时间自动恢复；输入 `/usage` 看额度和重置时间
`API Error: Request rejected (429)`	请求太频繁，被限流了	稍等再试；`/status` 看看是不是残留的 API Key 在用
`API Error: Repeated 529 Overloaded errors`	服务器一时太忙，跟你的额度无关	过几分钟再试，或者用 `/model` 换个模型
`Context limit reached · /compact or /clear to continue`	上下文装满了	`/compact` 或 `/clear`，见上下文窗口那篇

走 DeepSeek 时没有 Claude 订阅额度这回事，碰到余额或限流问题，去 DeepSeek 开放平台看账户。完整清单见官方的报错参考（面向开发者，偏技术）。

还不行：先体检，再按原来的方式重装

上面几招都试过还不行，按这个顺序来：

第一步：让它自己体检。 能进 Claude Code 就输入 /doctor；claude 根本启动不了，就在终端运行：

claude doctor

它会检查重复或残留的安装、PATH、坏掉的设置文件等，并给出修复建议；在会话里用 /doctor 的话，你确认后它还能直接修。

第二步：按当初的安装方式卸载、重装。 用什么装的就用什么卸，别混着来：npm 卸不掉原生版，再用 npm 装一次只会多出第二份。拿不准当初怎么装的，先运行 which -a claude（Windows：where.exe claude）看它在哪——路径在 .local/bin（Windows 是 .local\bin）下面的就是原生版。

原生安装（官方推荐的方式）卸载。Mac / Linux 用这两行：

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows（PowerShell）用这两行：

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

卸完照安装篇重新运行官方安装命令。

npm 装的才用 npm 卸载、重装（国内网络的写法见安装篇）：

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

Homebrew 装的用 brew uninstall --cask claude-code，WinGet 装的用 winget uninstall Anthropic.ClaudeCode，再用同一个工具装回来。

重装不会动你的设置和对话记录（它们在 ~/.claude 目录和 ~/.claude.json 里，别删）；API Key 这类环境变量设在 shell 配置文件里，也跟重装无关。

实在搞不定 → 去官方渠道找答案

如果你撞上的报错这 8 条都不在，可以：

先在 Claude Code 里输入 /doctor，让它自己检查安装和配置有没有问题
再去官方 GitHub 仓库的问题区 github.com/anthropics/claude-code/issues 搜一下报错里的关键词，很多问题别人已经遇到过，下面常有解决办法

新手常见的报错，大多在上面这几节里。遇到不要慌，Ctrl+F 跳到对应小节，照着一步步排查就行。

下一步

读完这一篇你应该有了 8 个最常见报错的速查能力——遇到不慌，有处可查。

接下来：

→ 怎么省钱：成本控制实战 —— 控制 Claude Code 花费的几个手法

→ 常用 Slash Commands —— /xxx 命令按「必背 / 常用 / 偶尔」分三档

想及时看到更新，可以收藏 niuxue.org 主页。