npm install 卡在 @anthropic-ai/claude-code 完整排坑记录

现象：npm 日志显示所有包都是 cache hit，下载已经完成，但进程一直卡住不动；同时伴随一条警告：npm warn Unknown user config "git-checks". This will stop working in the next major version of npm

一、先分清：警告 ≠ 卡死原因

npm warn Unknown user config "git-checks". This will stop working in the next major version of npm.

这条只是配置残留警告，不会导致安装卡住。 git-checks 是旧版 pnpm / 老 npm 遗留配置，新版 npm 已经不再识别该配置项。

清理命令：

npm config delete git-checks
# 验证配置
npm config list

执行完这条，后续就不会再弹出该警告。

二、真正卡住的根源：@anthropic-ai/claude-code 多平台二进制包

观察日志：

npm http cache @anthropic-ai/claude-code@... 0ms (cache hit)
npm http cache @anthropic-ai/claude-code-darwin-arm64@... 0ms (cache hit)

✅ 重点：cache hit 代表压缩包已经下载完毕，不是网络下载卡住。 claude-code 包含一套多平台二进制可选依赖：darwin-arm64 /darwin-x64 /win32 /linux/linux-musl。 下载完成后，npm 会进入下面流程，这一步极易假死：

1. 解压 tgz 压缩包
2. 识别本机操作系统 + CPU 架构
3. 筛选匹配当前机器的二进制程序
4. 执行包内置 postinstall 脚本（校验二进制、设置执行权限）

国内环境下，这个 postinstall 校验环节是高发卡点。

三、分层解决方案（按推荐顺序尝试）

方案 1：延长超时时间，直接重试（最简单）

npm install @anthropic-ai/claude-code --fetch-timeout 600000

方案 2：切换 pnpm（强烈推荐，二进制包稳定性远高于原生 npm）

pnpm 对 optionalDependencies、多平台二进制包的处理逻辑更成熟，不容易在 postinstall 阶段卡死。

# 全局安装pnpm
npm install -g pnpm
# 清理旧依赖
rm -rf node_modules package-lock.json
# 使用pnpm安装
pnpm install

方案 3：按需单独安装本机对应架构包（最轻量）

先查看本机平台架构：

node -p "process.platform + '-' + process.arch"

M 系列 Mac 输出一般是 darwin-arm64，直接单独安装对应二进制包，跳过其余平台包：

npm install @anthropic-ai/claude-code-darwin-arm64

方案 4：不想本地常驻依赖，直接 npx 临时调用

很多场景只是临时使用 claude-code，不需要写入项目依赖：

npx @anthropic-ai/claude-code

方案 5：跳过安装脚本兜底（适合紧急安装，后续需要手动处理二进制）

⚠️ 风险提示：--ignore-scripts 会跳过 postinstall，二进制不会自动配置，安装完成后需要手动解压、赋予执行权限。

npm install --ignore-scripts @anthropic-ai/claude-code

四、补充排查小技巧

1. 想看详细流程日志，定位卡死在哪一步：

npm install --verbose

2. 确认镜像源（使用 npmmirror 阿里镜像）

npm config get registry
# 如不是，执行
npm config set registry https://registry.npmmirror.com

3. 检查是否残留代理：

npm config get proxy
npm config get https-proxy
# 不需要代理则删除
npm config delete proxy
npm config delete https-proxy

五、小结

• git-checks：只是垃圾配置警告，清理即可，不影响安装；
• cache hit 不代表安装完成，claude-code 卡在postinstall 二进制校验阶段；
• 优先 pnpm，其次 npx 临时运行，最后再考虑 --ignore-scripts 兜底。