npm 全局安装的 CLI 工具报"不支持的 16 位应用程序 / 不是有效应用程序"——通用修复笔记

一、问题现象#

通过 npm install -g 安装后，在终端输入工具名（如 claude、opencode）或运行其 .exe 时失败。

典型报错（任选其一，本质相同）：

• 弹窗：不支持的 16 位应用程序
• 弹窗：由于与 64 位版本的 Windows 不兼容，此程序或功能无法启动或运行
• PowerShell：

  1
  Program 'claude.exe' failed to run: ... The specified executable is not a valid application for this OS platform.

• 部分用户还会看到：claude.exe 与你运行的 Windows 版本不兼容

共同特征：报错路径永远指向 ...\node_modules\<包名>\bin\<工具名>.exe

二、根本原因#

这类工具在 npm 上的”主包”只是一个启动器（wrapper），本身不含真正可执行的原生二进制；真正的 .exe 来自独立的平台原生包（命名形如 *-win32-x64、*-windows-x64）。

安装时，主包的 postinstall 脚本应把原生二进制复制/链接到 bin/<工具名>.exe。当该步骤因以下原因失败时：

• 国内网络被墙，无法从 GitHub / 官网下载原生二进制；
• 安全软件 / 杀毒拦截了写入；
• 旧版本残留污染了 PATH 或目录；
• ~/.npmrc 里设了 ignore-scripts=true：这会全局禁止 npm 执行安装脚本（含 postinstall），原生二进制因此完全不会被放置，最终 bin/<工具名>.exe 必然是 stub。装完会直接报错 claude native binary not installed. Either postinstall did not run (--ignore-scripts...)。该情况必须靠「手动复制真实二进制覆盖 stub」修复，npm 自身不会帮你放好。
• ~/.npmrc 里设了 min-release-age=N：会忽略发布不到 N 天的新版本，等效于给 npm 加了 before = 今天-N天 的日期过滤器。升级到较新版本（如 npm install -g <包>@<新版>）时会直接报 ETARGET ... No matching version found ... with a date before <某日期>。注意：npm view <包>@<新版> 能查到（它不过滤日期），但 npm install 会装不了。修复：删掉该限制（npm config delete min-release-age，恢复后可 npm config set min-release-age=N 重新加回），再安装。

bin/<工具名>.exe 会残留为一个无效的占位 stub（几百字节到几 KB）。Windows 无法将其识别为合法的 64 位 PE 文件，于是报上述错误。

结论：文件并未真的损坏，本质是原生二进制没有落位到正确路径。修复方式 = 找到真实二进制，覆盖占位文件。

三、前置说明：该用哪个终端、怎么复制命令#

• 全程使用 PowerShell（建议”以管理员身份运行”），可避免全局目录写权限问题。
• 不要把 Markdown 代码块的行首 ``` 和语言标识（如 powershell、bash）一起复制——它们不是命令，复制进去会报”无法识别的术语”。
• 本笔记所有命令均为 PowerShell 语法；若只用 Git Bash，核心 npm 命令一致，但 Remove-Item / Copy-Item / $env:APPDATA 需改写为 Bash 等价写法，故统一给 PowerShell。
• 国内用户必须走 npmmirror 国内镜像（步骤 3），不要从官方源 registry.npmjs.org 装，否则会超时。

四、分步解决方案#

1
npm uninstall -g @anthropic-ai/claude-code
2
npm uninstall -g @anthropic-ai/claude-code-win32-x64
3
npm uninstall -g opencode-ai
4
Remove-Item -Force -Recurse "$env:APPDATA\npm\claude.cmd" -ErrorAction SilentlyContinue
5
Remove-Item -Force -Recurse "$env:APPDATA\npm\claude.ps1" -ErrorAction SilentlyContinue
6
Remove-Item -Force -Recurse "$env:APPDATA\npm\claude" -ErrorAction SilentlyContinue
7
Remove-Item -Force -Recurse "$env:APPDATA\npm\opencode.cmd" -ErrorAction SilentlyContinue
8
Remove-Item -Force -Recurse "$env:APPDATA\npm\opencode.ps1" -ErrorAction SilentlyContinue
9
Remove-Item -Force -Recurse "$env:APPDATA\npm\opencode" -ErrorAction SilentlyContinue
10
Remove-Item -Force -Recurse "$env:APPDATA\npm\node_modules\@anthropic-ai" -ErrorAction SilentlyContinue
11
Remove-Item -Force -Recurse "$env:APPDATA\npm\node_modules\opencode-ai" -ErrorAction SilentlyContinue
12
npm cache clean --force

1
where.exe claude
2
where.exe opencode

1
npm config set registry https://registry.npmmirror.com
2
npm config get registry

1
npm install -g @anthropic-ai/claude-code@<版本号> --registry=https://registry.npmmirror.com
2
npm install -g @anthropic-ai/claude-code-win32-x64@<版本号> --registry=https://registry.npmmirror.com

1
npm install -g opencode-ai --registry=https://registry.npmmirror.com

1
Get-ChildItem "$env:APPDATA\npm\node_modules" -Recurse -Filter "claude.exe" -ErrorAction SilentlyContinue | ForEach-Object { "{0}   大小:{1}字节" -f $_.FullName, $_.Length }

1
Get-ChildItem "$env:APPDATA\npm\node_modules" -Recurse -Filter "opencode.exe" -ErrorAction SilentlyContinue | ForEach-Object { "{0}   大小:{1}字节" -f $_.FullName, $_.Length }

1
Copy-Item -Force "<真实二进制完整路径>" "<占位stub完整路径>"

1
Copy-Item -Force "C:\Users\21186\AppData\Roaming\npm\node_modules\opencode-ai\node_modules\opencode-windows-x64\bin\opencode.exe" "C:\Users\21186\AppData\Roaming\npm\node_modules\opencode-ai\bin\opencode.exe"

1
Copy-Item -Force "<真实二进制完整路径>" "$env:APPDATA\npm\<工具名>.exe"

1
$real = "<真实二进制完整路径，取自步骤 5 输出中较大的那个>"
2
Copy-Item -Force $real "$env:APPDATA\npm\node_modules\opencode-ai\bin\opencode.exe"
3
Copy-Item -Force $real "$env:APPDATA\npm\opencode.exe"
4
opencode --version

1
claude --version
2
opencode --version

五、常见疑问#

Q：为什么不能只装主包就完事？ A：主包不含原生 exe，必须依赖平台包；而 npm 在国内的 postinstall 链接步骤常因下载被墙失败，原生二进制没进 bin/。

Q：WinGet / 官方安装脚本为什么不算正解？ A：两者最终都从 downloads.claude.ai / claude.ai 下载，国内直连不通，会卡在下载阶段。本方案走 npm 国内镜像，可落地。

Q：会不会每次更新都复发？ A：有可能。若 npm update -g 后再次出现相同报错，直接重做「步骤 5 ～ 步骤 6」（定位真实二进制并复制）即可，无需重新安装。

Q：运行 opencode 提示”检测到多处安装”，并标记 AppData\Roaming\npm\opencode.exe 为”默认”且无法运行，怎么办？ A：这是 OpenCode 自身的安装自检，说明顶层 npm\opencode.exe 这个”默认”入口是坏的。npm postinstall 在升级时会把它写成坏壳。必须按上面的 OpenCode 必做项，同时把真实二进制复制覆盖到 node_modules\opencode-ai\bin\opencode.exe 与顶层 npm\opencode.exe 两处，再验证。仅覆盖一处仍会复发。

Q：怎么避免以后再复发？ A：根因是 npm 每次 install / update 都会重跑 postinstall、把 stub 重置回坏壳。已修好后，尽量不要执行 npm update -g opencode-ai；若确实需要升级版本，升级完成后重做一次「步骤 5 ～ 步骤 6」的复制即可。对追求一劳永逸的用户，可改用 Scoop（scoop install opencode，二进制直接落 ~/scoop/apps/opencode/current/opencode.exe）或手动从 GitHub Releases（走国内可达镜像）下载原生二进制放入 PATH，彻底绕开 npm 包装器。

Q：其它同类工具（也是 npm 包装器 + 原生 exe）能用同样方法吗？ A：能。把全文的 claude / opencode 换成对应工具名，按步骤 5 搜索其 .exe，找到 *-win32-x64 / *-windows-x64 下的真实二进制，覆盖 bin/ 下的占位文件即可。

Q：运行 opencode 时它提示”当前 1.18.11，最新 1.18.15，可升级”，是不是我又装错了？ A：不是装错。这里出现两个版本号是两个不同来源：

• 当前版本 1.18.11：来自你通过 npm 安装的 opencode-ai 主包版本（npm 源上当前最新的就是 1.18.11）。
• 最新版本 1.18.15：来自 OpenCode 运行时联网去 GitHub Releases 检测到的版本（GitHub 上已发 1.18.15）。 两者版本号不同步是常态。你手动复制的真实原生二进制配套的也是 1.18.11，所以当前能用。只要能正常运行，这行提示可以忽略，不必理会。

Q：想升级到 1.18.15（或其它新版）该怎么安全地升？ A：千万不要在 opencode 交互界面里点”升级”，那会去 GitHub 下载并重置 stub，大概率又回到坏壳状态（国内还常被墙）。正确做法二选一：

• 方案甲（仍走 npm，前提是 npm 源已发布该版本）：先 npm install -g opencode-ai@<目标版本> --registry=https://registry.npmmirror.com，装完重做「步骤 5～6」（定位新版本的真实原生二进制并复制到两处）。若 npm install 报 No matching version，说明 npm 源还没发该版，改用方案乙。

• 方案乙（手动落二进制，一劳永逸，推荐）：从 GitHub Releases 下载对应版本的 opencode-windows-x64.zip，解压出 opencode.exe，手动覆盖到顶层 npm\opencode.exe、node_modules\opencode-ai\bin\opencode.exe、以及平台包 node_modules\opencode-ai\node_modules\opencode-windows-x64\bin\opencode.exe 三处（覆盖平台包可避免自检报”多处安装”），再 opencode --version 验证。PowerShell 具体步骤（把 v<VERSION> 换成目标版本，如 v1.18.15；国内若 ghproxy.com 不通，换成 ghproxy.net 或删掉该前缀直连 github.com）：

  1
  $url = "https://ghproxy.com/https://github.com/anomalyco/opencode/releases/download/v<VERSION>/opencode-windows-x64.zip"
  2
  Invoke-WebRequest -Uri $url -OutFile "$env:TEMP\opencode-new.zip"
  3
  Expand-Archive -Path "$env:TEMP\opencode-new.zip" -DestinationPath "$env:TEMP\opencode-new" -Force
  4
  $real = (Get-ChildItem "$env:TEMP\opencode-new" -Recurse -Filter "opencode.exe" | Select-Object -First 1).FullName
  5
  Copy-Item -Force $real "$env:APPDATA\npm\node_modules\opencode-ai\bin\opencode.exe"
  6
  Copy-Item -Force $real "$env:APPDATA\npm\opencode.exe"
  7
  Copy-Item -Force $real "$env:APPDATA\npm\node_modules\opencode-ai\node_modules\opencode-windows-x64\bin\opencode.exe"
  8
  opencode --version

若不确定目标版本在 npm / GitHub 是否发布，先用 npm view opencode-ai versions 查 npm 已发版本，再决定走甲还是乙。

Q：Claude Code 怎么升级（比如 2.1.112 → 2.1.226）？它和 opencode 机制一样吗？ A：机制不同，不要套用 opencode 的 GitHub 下载法。 Claude Code 的正确升级渠道就是 npm 平台包，原生二进制在 npm 镜像上有同步，且主包 postinstall 会自动把平台包里的真二进制链接到 bin/，不必手动从 GitHub 拉。步骤：

1
# 1) 升级主包 + 平台包（两行顺序执行，均走国内镜像）
2
npm install -g @anthropic-ai/claude-code@<目标版本> --registry=https://registry.npmmirror.com
3
npm install -g @anthropic-ai/claude-code-win32-x64@<目标版本> --registry=https://registry.npmmirror.com
4
# 2) 验证
5
claude --version

两个包缺一不可：只装主包会得到坏 stub；平台包 @anthropic-ai/claude-code-win32-x64 必须与主包同版本。执行前可用 npm view @anthropic-ai/claude-code-win32-x64@<版本> version --registry=https://registry.npmmirror.com 先确认该版本平台包已发布。

安全网（仅当 claude --version 仍报”不兼容/无效应用程序”时跑）：手动定位平台包里的真二进制并覆盖到主包 bin/：

1
$real = (Get-ChildItem "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code-win32-x64" -Recurse -Filter "claude.exe" | Select-Object -First 1).FullName
2
Copy-Item -Force $real "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe"
3
claude --version

六、总结#

报错本质是 npm 包装器的 bin/<工具名>.exe 是未落位的占位 stub；通用解法 = 国内镜像重装主包与平台原生包 → 搜索定位真实原生二进制 → 复制覆盖占位文件 → 验证版本号。