所有文章

Claude Code 报错 “claude native binary not installed”:2 种原因和实测修法(2026)

“claude native binary not installed” 说明 npm 安装只完成一半:要么 postinstall 被跳过,要么平台包没下载。先看 node_modules/@anthropic-ai 里有什么,再选 install.cjs 或重装。npm 11 实测,npm 12 部分来自官方文档。

claude native binary not installed:空的黏土包装盒,旁边是散落的黏土齿轮和小终端窗口

先说结论:Error: claude native binary not installed. 的意思是 npm 安装只完成了一半。PATH 上的 claude 命令还是一个很小的占位脚本,原因要么是平台包根本没下载(--omit=optional,或 .npmrc 里写了 optional=false),要么是把真正二进制拷到位的 postinstall 步骤没执行(--ignore-scripts,或者 npm 12 的默认行为)。你属于哪种,决定了怎么修。我在 Linux 上用 Claude Code 2.1.319 和 npm 11.21.1 复现了两种情况,并测试了修法。npm 12 的部分来自 Anthropic 文档,因为我这里没有 npm 12。

占位脚本是什么

@anthropic-ai/claude-code 这个 npm 包本身很小。按 Anthropic 的安装排错页,真正的程序是按平台分发的可选依赖,比如 @anthropic-ai/claude-code-linux-x64,再由 postinstall 步骤拷贝到位。两步没都完成之前,claude 就是一个占位脚本,会打印:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

下面两次复现我看到的都是这段原文。文档说,Windows 上占位脚本是保存成 claude.exe 的脚本,所以 PowerShell 和 CMD 会报“无法运行该文件”,而不是打印这段话。

第 1 步:判断你属于哪种情况

看看 npm 装到的目录里有什么(全局安装用 npm root -g 找位置,本地安装看 node_modules):

ls node_modules/@anthropic-ai/
  • 同时有 claude-code 和 claude-code-linux-x64(或你平台对应的名字):二进制下载了,只是拷贝步骤被跳过。这是 --ignore-scripts 的情况。
  • 只有 claude-code:平台包根本没下载。这是 --omit=optional 的情况。

我的结果是这样:用 --ignore-scripts 时两个文件夹都在,运行 install.cjs 之后 bin/claude.exe 是约 340 MB 的真二进制。用 --omit=optional 时只有 claude-code,bin/claude.exe 是 500 字节的占位脚本。

情况 A:脚本被跳过(平台包在)

按报错提示,手动运行 postinstall:

node node_modules/@anthropic-ai/claude-code/install.cjs
claude --version

我在 npm install @anthropic-ai/claude-code --ignore-scripts 之后测了。修之前 claude 打印那段报错,修之后 claude --version 输出 2.1.319 (Claude Code)。

如果完全没法运行 postinstall,文档提到一个备用办法:找到已下载的包并启动它,代价是每次启动多一个 Node 进程:

node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs --version

这个在我的测试里也成功了(输出 2.1.319 (Claude Code))。

情况 B:可选依赖被跳过(平台包缺失)

再运行一遍 install.cjs 没用,因为根本没有二进制可拷。我测了,脚本输出:

[@anthropic-ai/claude-code postinstall] Native package "@anthropic-ai/claude-code-linux-x64" not found.
  This happens with --omit=optional or when the download failed; re-run the install to fetch it.

包装器输出 Could not find native binary package "@anthropic-ai/claude-code-linux-x64". 修法是找出是谁把可选依赖关掉了,然后重新安装。

  • 命令里去掉 --omit=optional(pnpm 是 --no-optional,Yarn 是 --ignore-optional)。
  • 检查 .npmrc 里有没有 optional=false。这条我测了:项目 .npmrc 里写 optional=false 后,直接 npm install @anthropic-ai/claude-code 只装了 claude-code 文件夹,npm config get omit 输出 optional。npm 自己也打印了一条配置警告,建议改用 --omit=optional。
  • 检查你的镜像源。Anthropic 文档说,公司内部的 npm 镜像除了主包,还必须同步全部八个平台包。

然后重新安装(全局安装用 npm install -g @anthropic-ai/claude-code),再运行 claude --version。

npm 12 与被跳过的 postinstall(来自官方文档)

这一部分我没法测试。文档说,除非你的配置允许,npm 12 完成安装时不会运行 postinstall 步骤。用 npm --version 检查,版本号以 12 开头的话,文档给了两条路:

  • 换用原生安装器,再卸载 npm 版。之后更新不再走 npm,这个错误就不会回来。
  • 留在 npm:如果版本是 12.0.x,要先升级到 12.1 或更新(例如 npm install -g npm@latest);保存 allow-scripts 设置之后,由 npx 工具或 npm run 脚本启动的项目安装可能会报 EALLOWSCRIPTS。先运行 npm config get allow-scripts 并记下它列出的内容,因为下一条命令会替换整个值。然后运行 npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user 并重新安装。如果因 EACCES 失败,文档说要改用原生安装器,不要用 sudo。

在我的 npm 11.21.1 上,直接安装会打印一条警告,说 Claude Code 的 postinstall 脚本“not yet covered by allowScripts”,但安装仍然成功,并放好了 340 MB 的二进制。不要假定 npm 12 上也一样。

如果报错还在

  • 确认没有旧的占位脚本排在 PATH 前面:type -a claude 应该只列出你想要的那一份。
  • 文档只列出 macOS、Linux(glibc 和 musl)、Windows 在 x64 与 arm64 上的预编译二进制。其他平台(包括 FreeBSD)不受支持。
  • 想不靠 npm 干净安装,参照 Claude Code 安装教程。其他 Claude Code 报错在报错清单里。

常见问题

这个报错是 Claude Code 本身坏了吗?

不是。程序本身没问题,是安装不完整。

sudo npm install -g 能解决吗?

单靠它不能。原因是步骤被跳过,不是权限,而且文档建议在出现 EACCES 之后不要用 sudo 重跑。

怎么一劳永逸地避免?

文档推荐原生安装器:它不经过 npm,所以没有可被跳过的 postinstall 步骤,之后更新也不走 npm。

来源与测试说明

  • Anthropic 文档:安装排错页,“Native binary not found after npm install” 一节(code.claude.com/docs/en/troubleshoot-install)。
  • 自己实测:Linux x64 上的 Claude Code 2.1.319 与 npm 11.21.1:--ignore-scripts、--omit=optional、.npmrc 里的 optional=false、install.cjs、cli-wrapper.cjs、直接安装。
  • 没测:npm 12、pnpm、Yarn、macOS 或 Windows、公司镜像。

留下你的想法

你的邮箱不会公开。