企业官网建设流程全解析

解决报错 Error: Missing optional dependency @openai/codex-linux-arm64

一图看懂：

问题复现：

uname-aLinux hostname-2pbfv.foreman.pxe5.10.0-282.0.0.184.oe2203sp3.aarch64#1 SMP Wed Sep 17 13:32:56 CST 2025 aarch64 aarch64 aarch64 GNU/Linunode-p"process.platform"linuxnode-p"process.arch"arm64

# npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com （用国内 NPM 镜像，可选）npminstall-g@openai/codex@latestsource~/.bashrc codex--version

这个报错的核心通常不是 Node.js 本身，而是 Codex 主包已经安装，但 Linux ARM64 平台对应的原生可执行依赖@openai/codex-linux-arm64没有被 npm 一起装上。常见原因包括 npm 配置、镜像源同步、架构识别以及残留安装，下面逐项排查。

Codex 的 Linux ARM64 二进制是通过optionalDependencies发布的。如果主包与平台包发布存在短暂时间差，npm install 可能正常退出，但实际缺少平台二进制，运行时会提示Missing optional dependency。OpenAI 的 Issue 中已经记录了类似情况。另外，我是全局 npm 安装，如果配置了omit=optional，或使用了同步不及时的镜像源，也会出现完全相同的报错。

因此，问题大概率是：@openai/codex的 JS 启动器已安装，但 Linux ARM64 所需的原生二进制包@openai/codex-linux-arm64没有落地。

推荐方案：继续使用 npm

如果希望继续通过 npm 管理，请先确认系统与 npm 配置：

uname-mnode-p"process.platform"node-p"process.arch"

正常应显示类似：

aarch64 linux arm64

然后检查npm是否禁用了可选依赖：

npmconfig get omitnpmconfig get optionalnpmconfig get registry

重点关注是否存在：

omit = optional

或

optional = false

如有，执行：

npmconfig delete omitnpmconfig delete optional

建议暂时切换到 npm 官方源，避免镜像同步延迟：

npmconfigsetregistry https://registry.npmjs.org/

重新干净安装：

npmuninstall-g@openai/codexnpmcache clean--force# npm install -g @openai/codex@latest --include=optional --registry=https://registry.npmmirror.com （用国内 NPM 镜像，可选）npminstall-g@openai/codex@latest--include=optional codex--version

最终解决了问题，2026 年 9 月 5 日@openai/codex的最新版本是0.153.4：

验证并确认ARM64 包是否落盘：

ls-la/root/.local/npm-global/lib/node_modules/@openai/codex/node_modules/@openai/ total12drwxr-xr-x.3root root4096Sep505:16.drwxr-xr-x.3root root4096Sep505:10..drwxr-xr-x.3root root4096Sep505:16 codex-linux-arm64

正常情况下，可以看到目录中除了codex，还应包含类似codex-linux-arm64的包。

如果问题依旧，请执行以下诊断命令：

echo"=== OS ==="uname-auname-mecho"=== Node ==="node-vnode-p"process.platform"node-p"process.arch"echo"=== npm ==="npm-vnpmconfig get registrynpmconfig get omitnpmconfig get optionalecho"=== Codex package ==="npmlist-g@openai/codex--depth=1||trueecho"=== OpenAI global modules ==="ls-lah/root/.local/npm-global/lib/node_modules/@openai/||true

其他方案：使用官方安装脚本

Codex 官方为 Linux 提供了独立安装脚本，可以绕过 npm 的 optional dependency 问题。

# 1. 移除 npm 安装的 Codex，避免 PATH 冲突npmuninstall-g@openai/codex# 2. 清除 shell 命令缓存hash-r# 3. 使用官方安装脚本curl-fsSLhttps://chatgpt.com/codex/install.sh|sh# 4. 验证command-vcodex codex--version

官方安装器会根据系统架构下载对应二进制，Linux ARM64 对应aarch64-unknown-linux-musl。这是最直接的解决方式。

Node.js v22.23.1 无需降级，Codex 对 Node 版本的要求低于此。问题核心不是 Node 版本，而是 ARM64 optional dependency 缺失。

如果希望尽快解决，可以直接执行这三条命令即可：

npmuninstall-g@openai/codexhash-rcurl-fsSLhttps://chatgpt.com/codex/install.sh|sh

然后运行codex --version确认是否成功了。