macOS 安装 Claude Code 卡在 npm postinstall 解决全记录

11次阅读

平台：Apple Silicon（M 系列 Mac），nvm 管理 Node，使用 npmmirror 淘宝镜像现象：npm install -g @anthropic-ai/claude-code 下载完各个平台包之后长时间卡住不动

问题复现命令

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com --verbose

日志关键特征

npm http fetch GET 200 https://registry.npmmirror.com/@anthropic-ai%2fclaude-code-darwin-arm64 4450ms (cache miss)
npm http cache @anthropic-ai/claude-code-darwin-arm64@... 0ms (cache hit)
⠇ 卡住

根因说明

@anthropic-ai/claude-code 的 npm 包本质只是一个引导壳包，真正的二进制文件由 postinstall 脚本二次拉取。即使切换到 npmmirror 镜像，镜像只能托管 tgz 源码包，postinstall 阶段的下载链路依然走官方地址，国内环境极易超时、卡死。另外这个 npm 包官方已经标记为 deprecated，不再推荐使用 npm 方式安装。

额外无关警告（不影响安装）
npm warn Unknown user config "git-checks". This will stop working in the next major version of npm.
原因：.npmrc 里存在老旧 git-checks 配置，后续新版 npm 会报错，可在 npmrc 文件删除该行。

方案一：官方推荐安装脚本（首选，强烈推荐）

绕过 npm 整套体系，直接使用 Anthropic 提供的一键脚本，自带自动更新逻辑，后续升级也不容易踩坑。

先卸载之前卡住没装好的旧包：

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

执行安装：

curl -fsSL https://claude.ai/install.sh | bash

安装完成后，新开终端直接调用：

claude

脚本访问困难时，可提前配置代理环境变量：
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

方案二：坚持使用 npm 安装（镜像优化版）

npm 默认会并行拉取全部平台（win/linux/mac）的可选二进制包，浪费大量时间。使用 --omit=optional 过滤多余平台包，指定当前架构。

npm install -g @anthropic-ai/claude-code \
  --registry=https://registry.npmmirror.com \
  --omit=optional \
  --platform=darwin \
  --arch=arm64

⚠️ 注意：--omit=optional 会跳过自动执行 postinstall，装好壳包后手动运行安装脚本：

node $(npm root -g)/@anthropic-ai/claude-code/install.cjs

方案三：手动下载二进制兜底方案（完全脱离 npm）

适合网络极差、脚本和 npm 都不可用的场景，直接拿对应版本 darwin-arm64 二进制放到 nvm 的全局 bin 目录。本次日志对应的版本：2.1.310

# 进入临时目录
cd $(mktemp -d)
# 下载 Mac ARM64 包
curl -O https://registry.npmmirror.com/@anthropic-ai/claude-code-darwin-arm64/-/claude-code-darwin-arm64-2.1.310.tgz
tar -zxf claude-code-darwin-arm64-2.1.310.tgz
# 拷贝二进制到 nvm 全局 bin（替换成你自己的nvm路径）
cp package/claude /Users/peterzhang/.nvm/versions/node/v26.10.0/bin/
chmod +x /Users/peterzhang/.nvm/versions/node/v26.10.0/bin/claude

拷贝完成，直接执行 claude 即可使用。