UBUNTU Claude Code 报错 claude native binary not installed

解决 Claude Code 报错：claude native binary not installed

最近安装 Anthropic Claude Code CLI 时，很多人遇到这个错误：

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.

这篇文章总结了问题原因和完整解决方案。

问题原因

Claude Code 的 npm 包采用了分拆包架构：

@anthropic-ai/claude-code — 主包，只是一个启动脚本和安装逻辑，不包含实际可执行二进制
@anthropic-ai/claude-code-<platform>-<arch> — 平台相关的可选依赖，实际原生二进制放在这里

常见出错场景：

1. npm 默认省略可选依赖

从 npm v7 开始，默认安装会加上 --omit=optional，所以平台相关包不会自动安装。这是最常见的原因。

2. PATH 顺序问题 / 多版本冲突

如果你之前装过失败版本，或者同时在多个位置（系统 /usr/bin 和 nvm）都有安装，shell 可能找到一个不完整的旧版。

3. nvm 用户特殊坑

如果你用 nvm 管理 Node.js，但 npm config get prefix 输出是 /usr 而不是 nvm 当前版本目录，就会：

全局安装必须 sudo
装完后仍然找不到二进制
PATH 冲突概率大大增加

4. 网络问题导致下载失败

install 脚本需要从 GitHub 下载二进制，如果网络不稳定，下载失败后就会留下占位符。

完整解决方案

下面按顺序操作，99% 的问题都能解决。

第一步：清理旧安装

先卸载可能存在的冲突版本：

# 卸载全局 npm 包
npm uninstall -g @anthropic-ai/claude-code @anthropic-ai/claude-code-linux-x64

# 如果之前用 sudo 装到系统目录，也清理一下
sudo npm uninstall -g @anthropic-ai/claude-code @anthropic-ai/claude-code-linux-x64

# 清理 nvm 里可能残留的旧链接（如果你用 nvm）
rm -f "$(which node)/../bin/claude"

第二步：修复 nvm 配置（仅 nvm 用户需要）

如果你用 nvm ，先确认 npm prefix 指向当前 nvm 版本，这样不需要 sudo 就能安装：

# 查看当前 nvm 版本
nvm current
# 输出类似: v22.16.0

# 设置 prefix 到当前版本
npm config set prefix "$HOME/.nvm/versions/node/$(nvm current)"

验证：

npm config get prefix
# 应该输出: /home/你的用户名/.nvm/versions/node/vXX.X.X

第三步：重新安装，包含可选依赖

# 安装主包，强制包含可选依赖
npm install -g --include=optional @anthropic-ai/claude-code

# 手动安装对应平台的二进制包（根据你的系统选择）
# Linux x86_64:
npm install -g @anthropic-ai/claude-code-linux-x64

# Linux arm64:
# npm install -g @anthropic-ai/claude-code-linux-arm64

# macOS Intel:
# npm install -g @anthropic-ai/claude-code-darwin-x64

# macOS Apple Silicon:
# npm install -g @anthropic-ai/claude-code-darwin-arm64

第四步：手动运行 postinstall 放置二进制

# 找到全局 node_modules 位置
CLAUDE_INSTALL_PATH="$(npm root -g)/@anthropic-ai/claude-code"

# 运行 postinstall 脚本
node "$CLAUDE_INSTALL_PATH/install.cjs"

第五步：解决下载失败（如果第四步还是报错）

如果第四步还是报找不到二进制，直接手动从 GitHub 下载：

# 目标目录
TARGET="$(npm root -g)/@anthropic-ai/claude-code-linux-x64/claude"
mkdir -p "$(dirname "$TARGET")"

# 下载 Linux x86_64 最新二进制
wget -O "$TARGET" https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64
chmod +x "$TARGET"

# 再次运行 postinstall
node "$CLAUDE_INSTALL_PATH/install.cjs"

其他架构请替换下载链接：

Linux arm64: claude-linux-arm64

macOS Intel: claude-darwin-x64

macOS Apple Silicon: claude-darwin-arm64

第六步：验证

# 刷新 shell 缓存
hash -r

# 检查位置和版本
which claude
claude --version

如果输出类似下面，就成功了：

/home/fk/.nvm/versions/node/v22.16.0/bin/claude
2.1.114 (Claude Code)

快捷解决方案：直接用官方安装脚本

如果你不想折腾 npm，可以跳过 npm，直接用官方脚本安装：

curl -fsSL https://cli.anthropic.com/install.sh | sh

脚本会自动下载对应平台二进制放到 ~/.local/bin/claude，不需要 Node.js，不需要 npm，一步到位。

如果 curl 连不上 GitHub，可以手动下载二进制放到 ~/.local/bin/ 即可：

mkdir -p ~/.local/bin
wget -O ~/.local/bin/claude https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64
chmod +x ~/.local/bin/claude

然后确保 ~/.local/bin 在你的 PATH 最前面。

总结

问题	解决方法
npm 自动省略可选依赖	`--include=optional` + 手动装平台包
nvm 用户权限不对	把 npm prefix 改回当前 nvm 版本目录
多版本 PATH 冲突	清理旧安装，刷新 hash 缓存
网络下载失败	手动从 GitHub 下载二进制放到对应位置

按照上面步骤走一遍，基本上就能解决 claude native binary not installed 错误了。