工具大全
踩坑实录作者:Coocon2026年9月29日344 次阅读约 11 分钟阅读

Claude Code 安装失败实测:npm EACCES、镜像卡 600 秒、Node 20 静默装旧版、install.sh 返回地区拦截页、原生安装器顺手卸掉 npm 版——15 条报错原文与解法

搜「claude code 安装」的人,大多数不缺教程——缺的是装到一半报错时,这句报错到底是什么意思。安装步骤本站已经有了(Claude Code 快速上手),这篇不重复,只做一件事:把安装会失败的地方在本机一个个真实复现,逐字记下报错原文、触发条件、耗时和退出码,再给出解法。

先说最意外的三条:

  1. Node 20 装 Claude Code 不会报错,而是静默装到 2.1.197。engines 从 2.1.198 起要求 >=22,npm 会自动挑一个旧的、满足条件的版本,没有任何警告。
  2. 在国内直连 curl -fsSL https://claude.ai/install.sh 时,curl 退出码是 0,下载下来的却是 447,830 字节的「App unavailable in region」HTML 页面。| bash 之后只会看到一句 syntax error near unexpected token '<'。
  3. 官方原生安装器会执行 npm uninstall -g @anthropic-ai/claude-code,把你已有的 npm 版删掉,终端里一个字都不提。本次实测就这样真的删掉了本机的全局安装——下面「踩坑」一节有完整经过。

假 npm 记录到原生安装器的调用:npm uninstall -g @anthropic-ai/claude-code

问题背景

Claude Code 现在有两条官方安装路径:

  • npm:npm install -g @anthropic-ai/claude-code。现在的包只是一个「壳」:真正的程序是平台对应的 optionalDependency(例如 @anthropic-ai/claude-code-darwin-arm64,tarball 98,952,459 字节)。postinstall 脚本 install.cjs 会把这个原生二进制硬链接到 bin/claude.exe。claude 命令本身已经不是 JS 了,而是一个 Mach-O 可执行文件(2.1.284 为 226,563,088 字节)。
  • 原生安装器:curl -fsSL https://claude.ai/install.sh | bash。脚本从 downloads.claude.ai 下载二进制、校验 sha256,然后执行 claude install,最终装到 ~/.local/bin/claude。

这两条路径各有各的失败面,而国内网络环境会让其中好几个失败面的报错看起来和真正的原因毫无关系。

问题分析

把「claude code 安装失败」拆开,能出问题的环节有这些:

环节 可能出的事 本文对应
写入全局目录 prefix 没有写权限 表中 #1
npm cache cache 目录不可写 #2
registry 连不上、DNS 解析不了、镜像慢 #3 #4 #6
代理 npmrc 与环境变量冲突 #5
Node 版本 engines 门禁 #7 #8
原生安装器 地区拦截、下载服务连不上、覆盖 npm 版 #9 #10 #12
装完之后 PATH、postinstall 没跑、用错启动方式 #11 #13 #14 #15

还有一个前提容易被忽略:npm install -g 读不到项目目录里的 .npmrc。实测在仓库根目录(其 .npmrc 写着 npmmirror),隔离 HOME 之后:

$ npm config get registry        → https://registry.npmmirror.com/
$ npm config get registry -g     → https://registry.npmjs.org/

也就是说,全局安装实际生效的只有 ~/.npmrc、全局 npmrc 和命令行参数。排查 registry / 代理问题时,一定要用 npm config get xxx -g 看。

技术方案与选型

目标是「真实复现 + 不破坏本机」,方案如下:

  • 所有安装都隔离:--prefix、--cache、--logs-dir 全部指向 /tmp/cc-install-0929/ 下的子目录,不写 ~/.npm 和 /opt/homebrew(原生安装器那一次例外,见「踩坑」)。
  • 失败面用可控的坏值触发:registry 指向 127.0.0.1:1 和 .invalid 域名,代理指向 127.0.0.1:1/:2,cache 用 0555 目录,权限用 /usr/local。
  • 低版本 Node 用便携版:本机的 22 / 24 / 25 都满足 >=22,于是在 /tmp 下解压了 Node v20.19.5(npm 10.8.2),不用 nvm,也不改系统。
  • 网络对照:镜像和官方源分别用独立 cache,否则第二次会命中相同 integrity 的缓存,测不出下载时间。

排除项:

  • 不测 Windows / Linux:只有一台 macOS,写不出没测过的报错原文。
  • 不测 sudo npm install -g:会写系统目录,而且这是网上最常见的错误建议,不值得为它破坏本机。
  • 不测 pnpm / yarn / bun:报错原文里提到了「some pnpm configs」,但本次没有复现,不下结论。
  • 不调用 API:安装问题与模型无关,全程 0 次 API 调用,花费 ¥0。

实测过程

  • 环境:macOS 26.3.1,Apple Silicon;Node v25.9.0,npm 11.11.0;北京直连,出口 AS4847,没有系统代理,也没有 TUN。
  • 本机原有 Claude Code 2.1.280(Homebrew 下的 npm 全局安装)。npm 上的 dist-tags 为 latest 2.1.284、stable 2.1.277,所以不钉版本时装到的是 2.1.284。
  • 每一组都记录了逐字命令、stdout+stderr、墙钟秒数和 exit code;带颜色的输出保留为 .ansi,截图用它渲染,没有手写的输出。
  • 时间:2026-09-29 10:02–10:37。

实践效果:15 条报错原文对照表

「解法已实测」一列标 ✅ 的,是本次在本机验证过的;标「未实测」的是依据报错文案或文档给出的建议。

# 报错原文(节选) 触发条件 墙钟 exit 解法 解法已实测
1 npm error code EACCES … Error: EACCES: permission denied, mkdir '/usr/local/lib' 全局 prefix 没有写权限 0.12s 243 不要 sudo。把 prefix 换到用户可写的目录(npm config set prefix ~/.npm-global,再把 ~/.npm-global/bin 加进 PATH),或者用 Homebrew / nvm 装的 Node ✅(所有 --prefix /tmp/... 的安装都成功)
2 Your cache folder contains root-owned files, due to a bug in previous versions of npm … sudo chown -R 501:20 "…" cache 目录不可写——本次属主就是自己,只是权限 0555 1.45s 1 先 ls -ld "$(npm config get cache)",看清是属主问题还是权限位问题;只有确实是 root 属主时才 chown 未实测(只验证了报错)
3 FetchError: request to http://127.0.0.1:1/… failed, reason: connect ECONNREFUSED 127.0.0.1:1 registry 端口不通 3.16s(缩短重试参数)/ 70.15s(默认参数) 1 npm config get registry -g 找出是谁配的,改掉 ✅
4 network request to https://nonexistent-cc-0929.invalid/… failed, reason: getaddrinfo ENOTFOUND registry 域名解析不了 3.86s 1 同上 ✅
5 request to https://registry.npmjs.org/… failed, reason: connect ECONNREFUSED 127.0.0.1:2 npmrc 里残留的 proxy=/https-proxy= 压过了环境变量 HTTPS_PROXY 0.13s 1 npm config get proxy -g 和 npm config get https-proxy -g 一起查,删掉残留项 ✅(换成空 userconfig 后恢复只读 env)
6 无报错,只是卡住:147.22s 装完 / 超过 600s 被我 kill 本机经 npmmirror 下载平台包 147s / >600s 0 / kill 加 --registry https://registry.npmjs.org 对照一次 ✅ 本机官方源 10.74s / 12.20s(各 2 个样本)
7 没有报错:added 2 packages in 21s,然后 claude --version → 2.1.197 Node <22 且不钉版本号 21s 0 升级到 Node ≥22;装完先看 claude --version ✅(Node 25 下装到 2.1.284)
8 npm warn EBADENGINE Unsupported engine / 加 --engine-strict 后变成 npm error code EBADENGINE Node <22 钉 @2.1.284 5.51s / 0.17s 0 / 1 同上 ✅
9 bash: line 1: syntax error near unexpected token '<'(HTML 的 <title>App unavailable in region</title>) 国内直连 claude.ai/install.sh 6.27s / 3.00s(两次) curl 0 先落盘 -o install.sh 再 head -1 看一眼;在国内改走 npm 路线,或者通过代理 ✅(走代理后拿到 9,704 字节的真脚本)
10 curl: (28) Failed to connect to downloads.claude.ai port 443 after 75595 ms 国内直连下载服务 75.63s 28 走代理 ✅(51.74s 装好)
11 Native installation exists but ~/.local/bin is not in your PATH 原生安装完成后 51.74s 0 按提示把 ~/.local/bin 加进 PATH(安装器不会自动改 ~/.zshrc) ✅
12 没有任何输出,后台执行了 npm uninstall -g @anthropic-ai/claude-code 之前用 npm 全局装过,再跑原生安装器 28.76s(安装器整体) 0 想保留 npm 版就别跑原生安装器;跑了的话,用 which -a claude 确认现在用的是哪一份 ✅(假 npm + strings 双证据,见下)
13 zsh:1: command not found: claude PATH 里没有 $(npm prefix -g)/bin 或 ~/.local/bin 0.11s 127 把对应的 bin 目录加进 PATH ✅
14 Error: claude native binary not installed. … node node_modules/@anthropic-ai/claude-code/install.cjs --ignore-scripts 安装,postinstall 没跑 0.84s npm 0,claude 1 去掉 --ignore-scripts 重装,或者手动 node "$(npm root -g)/@anthropic-ai/claude-code/install.cjs" 未实测
15 TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".exe" 按旧教程 node …/bin/claude --version — 1 直接执行 …/bin/claude --version ✅

下面挑几条展开。

#1 #2:权限类报错,第二条的诊断是错的

--prefix /usr/local 是最典型的 EACCES:0.12 秒就失败,exit 243,因为 mkdir '/usr/local/lib' 这一步就被拒了,所以没有留下半成品(/usr/local 实测与基线一致)。

npm install -g --prefix /usr/local:EACCES,exit 243

cache 那条更值得注意。我给 cache 目录设了 0555,属主就是当前用户 duoduo,npm 的报错却是「你的 cache 目录里有 root 拥有的文件,这是旧版 npm 的 bug」,并建议 sudo chown -R 501:20。照做修不好,因为问题根本不在属主。先 ls -ld 看清楚再动手。

cache 目录只是 0555,npm 却报 root-owned 并建议 sudo chown

#3 #4 #5:连不上时,npm 默认会等 70 秒

npm 默认 fetch-retries=2,退避 10s → 60s。registry 端口被拒(ECONNREFUSED)时,默认参数下 3 次尝试一共 70.15 秒才报错;把重试参数调短后是 3.16 秒。DNS 解析失败(ENOTFOUND)同样是 3 次尝试。看起来像「卡住了」的安装,不一定真卡住,可能只是在重试。

代理那条实测了 5 组:

环境变量 隔离 npmrc npm 实际连的
HTTPS_PROXY=:1 空 :1
HTTPS_PROXY=:1 https-proxy=:2 :2
HTTPS_PROXY=:1 proxy=:2 :2
无 proxy=:2 :2(proxy= 对 https registry 同样生效)
小写 https_proxy=:1 空 :1

结论:npmrc 里的代理配置优先于环境变量,哪怕写的只是 proxy=。报错文案里的 URL 是 registry,端口却是代理的端口,全文也没有点明这是代理的问题——很容易以为是 registry 挂了。另外,npm 走不走代理和 Node 内置 fetch 是两回事,后者不认 HTTPS_PROXY,见这篇。

#6:镜像 vs 官方源(只有 2 个样本)

组 registry 墙钟 exit
镜像第 1 次 npmmirror(经 ~/.npmrc) 147.22s 0
镜像第 2 次 npmmirror >600s,被 kill —
官方源第 1 次 registry.npmjs.org 直连 10.74s 0
官方源第 2 次 registry.npmjs.org 直连 12.20s 0

npm 调试日志显示,镜像慢在 cdn.npmmirror.com 上那个 99MB 的平台包:139,231ms;官方源同一个包是 6,881ms / 7,619ms。用 curl 单独拉镜像的同一个文件,125.7 秒后以 exit 35(SSL 连接错误)失败;官方源 7.66 秒,12.9 MB/s。

适用范围要说清楚:这是 2026-09-29 上午、北京、AS4847 出口、每组 2 个样本的结果,不能推广成「镜像一定比官方源慢」。但它说明一件事:「国内就该用镜像」不是无条件成立的,装不动时拿 --registry https://registry.npmjs.org 对照一次,成本只要十几秒。另外,被 kill 的那次在 prefix 里留下了只有 lib/ 的半成品目录。

#7 #8:Node 20 不会报错,而是装旧版

这一条是本次最隐蔽的。查 npm 上每个版本的 engines:2.1.197 及以前是 >=18.0.0,从 2.1.198 起是 >=22.0.0。在 Node v20.19.5 下:

  • 不钉版本:added 2 packages in 21s,exit 0,装到的是 2.1.197,没有任何警告;
  • 不钉版本 + --engine-strict:一样装到 2.1.197,照样没警告;
  • 钉 @2.1.284:只有 npm warn EBADENGINE,exit 0,装出来的二进制照样能跑(它是原生程序,不依赖 Node);
  • 钉 @2.1.284 + --engine-strict:npm error code EBADENGINE,exit 1,0.17 秒,并留下一个空的 lib/。

Node v20.19.5:不钉版本静默装到 2.1.197;钉 @2.1.284 只有 EBADENGINE 警告

所以如果你在 Node 18/20 上装完发现「文档里的新功能怎么没有」,先看一眼 claude --version。

#9 #10 #11 #12:原生安装器的四个坑

**地区拦截页被当成脚本。**国内直连时 claude.ai/install.sh 先 302 跳到 claude.com/app-unavailable-in-region,再返回 200 text/html。curl -fsSL 的 -f 只对 HTTP 错误码生效,所以 curl 退出码是 0。10:19 和 10:37 两次复现结果一致,都是 447,830 字节。

北京直连 claude.ai/install.sh:curl exit 0,拿到的是地区拦截页 HTML

**下载服务连不上。**用代理拿到真脚本后,在直连下运行:脚本在第一步请求 downloads.claude.ai/claude-code-releases/latest 时,curl 75,595 ms 后报 (28)。脚本里其实写了友好提示(not available in your region),但因为 set -e 加命令替换,脚本直接以 curl 的 28 退出,友好提示没有机会显示。

**走代理能装好,但 PATH 要自己加。**51.74 秒装好 2.1.284,产物是 ~/.local/bin/claude → ~/.local/share/claude/versions/2.1.284(约 216MB)。安装器提示 ~/.local/bin is not in your PATH,给出了 echo … >> ~/.zshrc,但不会替你执行。

**它会卸掉你的 npm 版。**原生二进制的 install 子命令会检查是否存在 npm 全局安装,如果有,就执行 npm uninstall -g @anthropic-ai/claude-code。我用两种互不依赖的方法确认了这一点:

  1. 假 npm:在 PATH 最前面放一个只记录参数、然后 exit 0 的 npm,同时设置 npm_config_prefix 指向隔离目录做双保险,再执行 claude install。记录下来的调用只有一条:[uninstall] [-g] [@anthropic-ai/claude-code]。
  2. strings:在 2.1.284 二进制的偏移 189061680 处找到 qe("npm",["uninstall","-g",e],{cwd:process.cwd(),…}),成功后调用 t(\Removed global npm installation of ${e}`)`——这是写日志,不是终端输出,所以屏幕上看不到。

安装器的终端输出从头到尾只有 Checking installation status… / Installing… / ✔ Claude Code successfully installed!。从产品角度这大概是有意的「迁移」,但如果你同时依赖 npm 版(比如脚本里写死了 /opt/homebrew/bin/claude),它就会悄无声息地失效。

#14 #15:装完了却跑不起来

--ignore-scripts 安装:npm exit 0,看上去一切正常(安装加运行整组 0.84 秒),但 bin/claude.exe 只有 500 字节,是个占位文件,一运行就报 Error: claude native binary not installed.,exit 1。报错文案本身写得很清楚,给出了手动跑 postinstall 的命令。

--ignore-scripts:npm exit 0,但 bin/claude.exe 只是 500 字节占位

老教程里的 node $(npm root -g)/@anthropic-ai/claude-code/…/claude 这种写法已经不能用了:node …/bin/claude --version 报 ERR_UNKNOWN_FILE_EXTENSION ".exe",因为那是 Mach-O 二进制,直接执行即可。

装好、能跑之后,如果登录时报 Invalid API key / Not logged in,那是认证问题,不是安装问题,见 Claude Code 认证报错实测。

未复现 / 不适用

  • --omit=optional 未复现:报错文案说它会导致缺少二进制,但在 npm 11.11.0 的全局安装里,平台包照样装上了,claude --version 正常。
  • 「换个 Node 版本就跑不起来」不适用:产物是原生二进制,otool -L 只链接了系统库;Node 20 / 22 / 25 下都能运行,cli-wrapper.cjs 也是。所谓 ABI 问题在当前版本已经不存在。
  • 同版本重装:npm 显示的是 changed 2 packages(4.80s,再来一次 0.87s),而不是 up to date。

踩坑

**只隔离 HOME,挡不住全局 npm 的写入。**跑原生安装器时,我把 HOME 指向了 /tmp,以为这样就隔离了。结果安装器执行的 npm uninstall -g 用的是 npm 内置配置里的全局 prefix(/opt/homebrew),这个 prefix 和 HOME 无关——本机真实的 2.1.280 全局安装就这样被删掉了,claude 直接变成 command not found。之后用 npm install -g @anthropic-ai/claude-code@2.1.280 --registry https://registry.npmjs.org 恢复,约 3 秒。所以第 12 条的证据才会有三份:一份意外撞出来的 npm 调试日志(argv "uninstall" "--global" "@anthropic-ai/claude-code"),外加事后用假 npm 和 strings 做的安全复现。跑别人的安装器前,要么设 npm_config_prefix 指向隔离目录,要么把 npm 移出 PATH。

curl -f 挡不住地区拦截页。-f 只看 HTTP 状态码,302 跳转后的 200 HTML 它照单全收。curl … | bash 前先落盘看一眼。

**PATH 里的空格。**复现第 12 条时,第一次的 env PATH=$T/shim:$PATH … 因为 PATH 里有 VMware Fusion.app 这样带空格的目录而解析失败,exit 127——好在安装器根本没有执行。拼 PATH 时要加引号。

**把 --ignore-scripts 当成标题传给 npm run。**用 npm run term-shot … "--ignore-scripts:…" 出图时,npm 把以 -- 开头的标题当成了自己的参数吞掉了,两张图的标题都成了默认值。要写成 npm run term-shot -- …。

相关文章

这类实测,每周六汇总一封

订阅码农早餐:每天 8:00 一封 AI 编程早报,每周六另附本周 Claude Code / Codex / 本地模型的实测和踩坑汇总。

相关文章

Claude Code 禁止 rm -rf 怎么配:deny 规则两周拦下 14 次,实测还有 7 种写法照样能删,一个 hook 补齐

为了防 Claude Code 误删文件,我在全局 settings 里加了一条 deny 规则 Bash(rm -rf *)。翻本机 10 月 7 日到 21 日的会话记录:这条规则拦下 14 次删除,模型被拒后 8 次换新目录名、6 次直接放弃删除,一次都没换写法绕过。但在 Claude Code 2.1.285 上用 stub 逐字回放 22 种删除写法后发现:rm -fr、rm -r -f、rm -Rf、rm -r 在手动、auto、bypass 三种模式下都照删不误,/bin/rm、find -delete、bash -c 在手动和 bypass 模式下也能删。auto 模式下,工作目录内的 rm -fr 会被当成「acceptEdits 也会放行」的操作,连分类器都不过。另一道闸是内置的 dangerous-rm 检查,目标是 $D/* 这类变量展开时触发,bypass 模式也拦;多行命令里前面有 heredoc,它就跟不上同一条命令里的变量赋值。文末给出一个 PreToolUse hook,三种模式下补齐全部递归删除写法,并告诉模型被拒后该怎么做。

claude-codehooks+5
pitfalls2026年10月21日7 min
920

Claude Code 接 DeepSeek / GLM / Kimi 开 auto 模式:temporarily unavailable 括号里的原因怎么看,哪些重试没用(故障注入实测)

用第三方模型跑 Claude Code auto 模式,每个有副作用的动作都会用你的会话模型向同一个后端多发一次判定请求:系统提示词 132,470 字符,单次约 2.97 万输入 token,比主循环那一步还多。判定请求一失败,就出现「xxx is temporarily unavailable, so auto mode cannot determine the safety of Bash」。本文用故障注入代理把每种失败对应的报错原文测了一遍:500 → (server error)、429 → (rate-limited)、529 → (overloaded)、断连 → (connection failed),这几种会自动重试 5 次;超过 60 秒没回 → (timed out);**没有括号 = 后端拒收(4xx),只试 1 次,重试多少遍都一样**;后端回了但模型没给判定 → could not evaluate,连续 3 次就退回人工确认。另外实测 CLAUDE_CODE_AUTO_MODE_MODEL 不生效,判定器只能跟着会话模型换。Claude Code 2.1.285,真实后端 DeepSeek v4-pro 与小米 MiMo v2.5。

claude-codedeepseek+7
pitfalls2026年10月11日11 min
1865

Claude Code 上下文太长怎么办:Prompt is too long 会自动压缩,中转站 / DeepSeek 的 maximum context length 却不会(实测)

Claude Code 靠报错文案判断「上下文太长」:后端说 prompt is too long 或 input is too long for requested model,它会自动压缩对话后重发,用户无感;DeepSeek 和 OpenAI 风格中转返回的 This model's maximum context length is …,它不认识,直接报 API Error: 400,每轮都失败。手动 /compact 有效;更好的办法是用 CLAUDE_CODE_MAX_CONTEXT_TOKENS(非 claude- 模型 ID)或 CLAUDE_CODE_AUTO_COMPACT_WINDOW(claude- 模型 ID)告诉它真实上限,让它提前压缩。Claude Code 2.1.285 + 本地 stub 实测。

claude-codedeepseek+6
pitfalls2026年10月5日8 min
1464

Claude Code 一直卡住、转圈没反应怎么办:后端不回时它要等 6 分钟,重试满 10 次可能卡一个多小时(实测)

Claude Code 转圈不动、或者停在 Retrying in 0s,多半是后端没有回数据。实测 2.1.285(API key + ANTHROPIC_BASE_URL):后端不回响应头时每次等 6 分钟(360 秒)才判超时,把 API_TIMEOUT_MS 调到 60 万、90 万也不变,只能调小;默认重试 10 次,总共可能卡一个多小时。中转站如果把回复缓冲到生成完才返回,超过 6 分钟的回复永远拿不到。按 Esc 可以随时中断。全部在本地 stub 上实测。

claude-code中转站+6
pitfalls2026年10月5日10 min
1275