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

📍 进阶 6/10 · 上一篇:← checkpoint 用法

这一篇的正确读法

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

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

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

8 个最常见报错总览

序号	你看到的关键词	章节锚点
1	command not found: claude	跳到第 1 节
2	401 / Authentication failed	跳到第 2 节
3	connection refused / ENOTFOUND	跳到第 3 节
4	CPU 100% / 风扇狂转 / 卡顿	跳到第 4 节
5	AI 改错了,我撤不回来	跳到第 5 节
6	tool use 卡住不动	跳到第 6 节
7	中文显示 ??? / 方框乱码	跳到第 7 节
8	/clear 也没用,怎么硬重启	跳到第 8 节

---

1. command not found: claude

症状

打开终端输入 claude,终端报:

bash: command not found: claude
zsh: command not found: claude

原因

Claude Code 装好了但 PATH 没刷新——你的 shell 还不知道 claude 这个命令存在。

修复

Mac / Linux — 重新 source 一下 shell 配置:

source ~/.zshrc      # 如果你用 zsh
source ~/.bashrc     # 如果你用 bash

或者直接关掉重开一个终端(最简单)。

Windows(PowerShell):

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","User") + ";" + [System.Environment]::GetEnvironmentVariable("Path","Machine")

或重启 PowerShell。

如果还是不行,说明根本没装上,跑一遍:

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

(如果不熟 npm 安装,看装一个 Claude Code)

---

2. 401 / Authentication failed

症状

启动 claude 后立刻报:

Error: 401 Unauthorized
Error: Authentication failed
Error: Invalid API key provided

原因

3 种情况之一:

• API key 没设(环境变量 ANTHROPIC_AUTH_TOKEN 是空的)
• API key 错了(打字错了 / 复制粘贴丢字符)
• endpoint 跟 key 不匹配(你用的是 DeepSeek 的 key,但 endpoint 还是 Anthropic 的)

修复

Step 1:看一下你的 key 是不是真的设了:

echo $ANTHROPIC_AUTH_TOKEN

如果输出是空,重新设一遍。临时设:

export ANTHROPIC_AUTH_TOKEN="sk-你的-真实-key"

永久设(加到 ~/.zshrc 或 ~/.bashrc):

echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的-真实-key"' >> ~/.zshrc
source ~/.zshrc

Step 2:确认 base URL 跟 key 来自同一家。

如果你用 DeepSeek + Claude Code 配置,base URL 必须是 DeepSeek 的:

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"

走 Anthropic 官方就不要设 base URL,让它默认走 api.anthropic.com。

📚 详细配置看Claude Code + DeepSeek 配置详解。

---

3. connection refused / ENOTFOUND

症状

启动 claude 后报:

Error: connect ECONNREFUSED 127.0.0.1:443
Error: getaddrinfo ENOTFOUND api.deepseek.com
Error: fetch failed

原因

网络问题——你的电脑根本连不上 API 服务器:

• DNS 错了 / 被 hosts 文件改坏
• 公司 / 学校的代理设置错了
• 你的网络限制了访问目标域名
• 走 Anthropic 但你在中国大陆(被墙)

修复

Step 1:看你能不能 ping 通:

ping api.deepseek.com         # 国内路径
ping api.anthropic.com        # 海外路径

ping 不通 → 是网络问题,跟 Claude Code 无关。

Step 2:检查你设的 base URL 有没有打错字:

echo $ANTHROPIC_BASE_URL

应该是:https://api.deepseek.com/anthropic (注意是 .com 不是 .cn)

Step 3:国内常见情况——如果你没设 ANTHROPIC_BASE_URL,它默认走 api.anthropic.com,在中国大陆直接连不上。修复:

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"

---

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

症状

跟 Claude Code 聊一会,电脑风扇开始狂转,CPU 飙到 100%,整个系统卡顿。

原因

最常见是 auto-compact 反复触发——你的对话太长、读了太多大文件,context 一直在 95% 以上,Claude 反复在做「自动压缩 → 又满 → 又压缩」的循环。

修复

第一时间:

/clear

(强制清空 context,从零开始)

或者更稳的:

Ctrl+C            # 杀掉当前对话
claude            # 重新启动

长期对策:

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

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

---

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

症状

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

原因

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

修复

在 Claude Code 内输入:

/checkpoint

会列出最近所有自动存的 checkpoint。挑一个改之前的版本,跑:

/checkpoint <编号>

按 y 确认,所有 checkpoint 之后的改动全部撤销。

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

⚠️ 关键提醒:checkpoint 在 Claude Code 进程关掉后仍然保留,但重装 / 升级可能丢。回滚完立刻 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 在等一个挂掉的服务器)

修复

第一步:按 Ctrl+C 中断当前工具调用。

如果 Ctrl+C 没用,强制中断:

Esc Esc Esc    # 连按 3 下 Esc

如果还没反应,外部杀进程:

# 另开一个终端
pkill -f "claude"

⚠️ 用 pkill -f 时要精确——pkill -f claude 会误杀其他叫 claude 开头的进程。建议先看一眼:

pgrep -fa claude    # 先看清楚哪些进程

确认后再杀。

长期对策:

• 让它读文件前先告诉它「这个文件可能很大,你扫前 200 行就够」
• 跑 Bash 命令前看一眼是不是 long-running(避免 tail -f、watch)
• 用 timeout 10 curl ... 给 curl 加超时

---

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

症状

Claude 输出中文时显示:

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

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

原因

终端的字符编码没设 UTF-8。

修复

Windows(命令提示符 / PowerShell):

chcp 65001

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

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 用户):

• 设置 → Profiles → Defaults → Advanced → Text Encoding 改 UTF-8
• 字体也换一个支持中文的(微软雅黑 / Consolas + 中文 fallback)

---

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

症状

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

原因

进程真的死了——可能是 Node.js 内存爆了、网络 stack 卡住、或者 Bash 子进程挂起。

修复

Mac / Linux:

# 另开一个终端
pkill -f "claude"

# 等 3 秒
sleep 3

# 重新启动
claude

Windows(PowerShell):

Get-Process -Name node | Where-Object { $_.MainWindowTitle -like "*claude*" } | Stop-Process -Force
claude

如果连 pkill 都杀不掉(很罕见):

# 杀所有 node 进程(谨慎——会杀掉其他 node 应用)
killall -9 node

⚠️ killall -9 node 会连带杀掉所有 Node.js 应用(包括 VS Code 插件、本地 dev server)。能不用就不用。

长期对策:

• 内存爆 → 关掉浏览器再开 Claude Code
• 网络卡 → 重启路由器试试
• 频繁出现 → 升级 Claude Code 到最新版:npm update -g @anthropic-ai/claude-code

---

一个万能 fallback:重装

上面 8 招都试过还不行,核武器选项:

# 1. 卸载
npm uninstall -g @anthropic-ai/claude-code

# 2. 清缓存
npm cache clean --force

# 3. 重装
npm install -g @anthropic-ai/claude-code

# 4. 重新启动
claude

99% 的奇怪问题这一招能解决——前提是你的 API key 跟环境变量没丢(它们是设在 shell 配置里的,跟 Claude Code 本身分离)。

实在搞不定 → 找我们

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

• 把完整报错截图 + 你跑的命令发邮箱 [email protected]
• 我们会回复修复方案,也会精选加进这一篇

新手第一年的报错,99% 都在这 8 条里。遇到不要慌,Ctrl+F 跳到对应小节,抄一行命令就完事。

下一步

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

接下来:

→ 怎么省钱:成本控制实战 —— Claude Code 月费砍到三十块的 4 个手法

→ Slash Commands 全清单 —— 30+ 个 /xxx 命令的「必背 / 常用 / 偶尔」三档

想第一时间收到,可以收藏 niuxue.org 主页。

---

如果你撞上一个这 8 条都不在的报错并且自己摸索出修复,告诉我们 [email protected],加进文章会贡献给整个社区。