🤖Claude Code (npm) Windows 安装问题排查与解决

📋 问题背景与环境

问题背景

在两台 Windows 11 电脑上通过 npm i -g @anthropic-ai/claude-code 安装 Claude Code CLI：

  • 机器 A（正常）：D:\node\nodejs\node_global\node_modules\@anthropic-ai\claude-code\bin\claude.exe 大小约 234MB，claude 命令可正常使用。
  • 机器 B（异常）：同一命令安装后，claude.exe 只有 约 1KB（与 npm 仓库页面显示的源文件大小一致），claude 命令无法正常运行。

疑问：

  1. 为什么 npm 仓库上显示 claude.exe 只有 1KB，机器 A 却是 234MB？
  2. 为什么同样 Windows 11 的机器 B，却拿不到 234MB 的真实二进制？
  3. 如何在机器 B 上重装、补齐 win32-x64 平台的原生二进制？

环境信息

项 值
操作系统 Windows 11 Pro（两台都是）
包管理器 npm（全局安装模式）
Node 全局目录 D:\node\nodejs\node_global\
目标包 @anthropic-ai/claude-code（版本 2.1.114）
目标 CPU 架构 win32-x64
Node 要求 >=18.0.0（主包 package.json 的 engines 字段声明）

结论速览

  • npm 仓库里的 bin/claude.exe 本来就是 1KB 占位 stub，真二进制藏在平台相关的 optionalDependencies 子包中，由 postinstall 脚本（install.cjs）在安装时硬链接到主包位置。
  • 机器 B 失败是因为平台子包 @anthropic-ai/claude-code-win32-x64 没装上（通常由镜像源未同步、optional 被禁用、或 postinstall 被跳过导致），stub 没被替换。
  • 修复命令（实测一条搞定）：
    npm i -g @anthropic-ai/claude-code --include=optional --foreground-scripts --registry=https://registry.npmjs.org/ --verbose

下文给出完整的原理、诊断与修复方案。

📦 一、包架构背景（理解这点，问题一目了然）

@anthropic-ai/claude-code 是一个分发壳包，真正的原生二进制在 8 个平台相关的 optionalDependencies 子包中：

@anthropic-ai/claude-code              ← 主包（~几 MB，含 install.cjs）
├── @anthropic-ai/claude-code-win32-x64    ← Windows x64 原生 exe（~234MB）
├── @anthropic-ai/claude-code-win32-arm64
├── @anthropic-ai/claude-code-darwin-arm64
├── @anthropic-ai/claude-code-darwin-x64
├── @anthropic-ai/claude-code-linux-x64
├── @anthropic-ai/claude-code-linux-arm64
├── @anthropic-ai/claude-code-linux-x64-musl
└── @anthropic-ai/claude-code-linux-arm64-musl

安装流程

  1. npm 下载主包，主包 bin/claude.exe 本身是 1KB 占位 stub。
  2. npm 按当前平台从 optionalDependencies 中只挑匹配的一个下载（Windows x64 机器拉 claude-code-win32-x64）。
  3. 主包的 postinstall 脚本 install.cjs 执行：
    • 用 require.resolve 找到平台子包的真二进制路径
    • 通过 linkSync（硬链接，零额外磁盘占用）或 copyFileSync（跨盘/无权限回退）
    • 覆盖主包 bin/claude.exe 的 stub

安装成功的标志：bin/claude.exe 大小 ≈ 234MB（nlink=2 说明是硬链接，不是双倍占用）。

🔍 二、症状识别

现象 判定
bin/claude.exe 只有 ~1KB ❌ postinstall 未成功，原生二进制没替换进来
bin/claude.exe ≈ 234MB ✅ 正常
运行 claude 报错或退出码异常 需进一步查日志

快速检查：

# Git Bash / PowerShell
ls -la "D:/node/nodejs/node_global/node_modules/@anthropic-ai/claude-code/bin/"

🎯 三、常见根因（按出现频率排序）

1. 私有镜像/国内镜像未同步平台子包 ⭐ 最常见

  • 淘宝源、腾讯源、公司私服等只同步了主包，没同步 claude-code-win32-x64 子包。
  • npm 拉不到 optional 包时静默跳过（这是 optional 的定义），不报错。
  • 结果：主包装成功，但 stub 没被替换。

验证：

npm config get registry
npm view @anthropic-ai/claude-code-win32-x64 version

第二条命令如果报 404 或无输出，就是镜像没同步。

2. --ignore-scripts 或相关配置关闭了生命周期脚本

postinstall 不执行 → 平台包下载了也不会替换 stub。

验证：

npm config get ignore-scripts

3. 配置禁用了 optional 依赖

  • .npmrc 写了 omit=optional / optional=false
  • 环境变量 NPM_CONFIG_OMIT=optional
  • 历史命令跑过 npm config set omit optional
  • 用了 --omit=optional / --no-optional / 老 npm 的 --production

验证：

npm config get omit
npm config list

4. Node 架构不匹配

32-bit Node 跑在 64-bit Windows 上 → process.arch === 'ia32'，install.cjs 里 PLATFORMS 没这条，报 Unsupported platform。

验证：

node -p "process.platform + '-' + process.arch"
# 必须输出 win32-x64 或 win32-arm64

5. npm 版本过旧

npm 7+ 才对 optionalDependencies 的平台筛选做得可靠。

验证：

npm -v   # 建议 ≥ 10
node -v  # 主包要求 ≥ 18

6. 用 pnpm / yarn 替代 npm

pnpm 老版本对 optional platform 包解析有坑；yarn classic 行为也不同。官方推荐用 npm 安装。

🩺 四、诊断清单（一次性跑完）

出问题的机器上按顺序执行：

node -p "process.platform + '-' + process.arch"
node -v
npm -v
npm config get registry
npm config get omit
npm config get ignore-scripts
npm view @anthropic-ai/claude-code-win32-x64 version

把输出保留下来，对照上面根因章节就能定位。

🔧 五、修复方案

方案 A：标准重装（覆盖 90% 情况）⭐ 推荐首选

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

npm i -g @anthropic-ai/claude-code \
  --include=optional \
  --foreground-scripts \
  --registry=https://registry.npmjs.org/ \
  --verbose

参数详解

参数 作用
-g 全局安装，命令在任意目录可用
--include=optional 显式强制装 optionalDependencies，覆盖所有关闭配置（等价于清空 omit 列表）
--foreground-scripts postinstall 日志打到前台，失败立刻可见，避免静默留下 stub
--registry=https://registry.npmjs.org/ 本次命令走官方源，绕过未同步子包的镜像；不改全局 config
--verbose 打印 HTTP 请求、tarball 下载、脚本执行每步，便于定位

执行时重点看 postinstall 输出：

  • ✅ 没有 Native package ... not found → 成功
  • ❌ 看到 Native package "@anthropic-ai/claude-code-win32-x64" not found → 方案 B
  • ❌ 看到 Unsupported platform → 方案 D

方案 B：手动同时装主包 + 平台包

镜像同步问题的兜底：

npm i -g @anthropic-ai/claude-code @anthropic-ai/claude-code-win32-x64 \
  --registry=https://registry.npmjs.org/

方案 C：postinstall 没跑，手动触发

主包文件齐全但 bin/claude.exe 还是 stub：

cd "D:\node\nodejs\node_global\node_modules\@anthropic-ai\claude-code"
node install.cjs

方案 D：Node 架构错了

卸载 32-bit Node，从 https://nodejs.org/ 下载 Windows x64 LTS Installer 安装，再重跑方案 A。

方案 E：跨机器拷贝（终极兜底）

从已安装成功的机器：

  1. 压缩整个目录：D:\node\nodejs\node_global\node_modules\@anthropic-ai\
  2. 拷到新机器相同路径并解压
  3. 确认 D:\node\nodejs\node_global\ 下有 claude.cmd（npm cmd-shim），没有就手动建一个：
@echo off
"%~dp0\node_modules\@anthropic-ai\claude-code\bin\claude.exe" %*

✅ 六、验证安装成功

ls -la "D:/node/nodejs/node_global/node_modules/@anthropic-ai/claude-code/bin/"
# claude.exe 应 ≈ 245966496 字节 (~234MB)

claude --version

🎬 七、本次实战记录

  • 症状：Windows 11 机器 A 安装正常（234MB），机器 B 只有 1KB stub。
  • 定位：机器 B 的 npm 未成功装 @anthropic-ai/claude-code-win32-x64 平台子包。
  • 解决：方案 A 一条命令搞定：
    npm i -g @anthropic-ai/claude-code --include=optional --foreground-scripts --registry=https://registry.npmjs.org/ --verbose
  • 关键洞察：
    1. 主包 1KB 的 claude.exe 是 stub，真二进制靠 postinstall 替换
    2. optional 依赖失败会静默跳过，不会让主包安装失败
    3. 镜像源未同步子包是最常见元凶，指定官方 registry 立即绕过

📚 八、延伸参考

  • 此模式和 Bun 的 npm 包（bun 主包 + @oven/bun-* 平台包）完全一致，排查思路通用。
  • 同类架构的包（esbuild、swc、turbo、rollup 的原生模块等）出现"装了但跑不起来"时，套路都是：检查平台子包是否下载 + postinstall 是否执行。
posted @ 2026-04-22 09:56  丿似锦  阅读(640)  评论(0)    收藏  举报