记录了在 Linux 系统上安装 @openai/codex 时的常见问题及解决方案。主要涉及 Node.js 版本过低导致的安装失败，以及因网络限制导致的 NVM 安装和 Node.js 版本列表获取失败。通过手动下载 NVM 压缩包、配置国内镜像源（如 npmmirror）以及使用 Gitee 镜像解决 Git 克隆问题，成功完成了 Node.js 环境升级至 v20+ 并安装了 Codex 工具。文章提供了详细的排查步骤和核心命令总结，适用于 Ubuntu/Debian 等基于 Linux 的系统。
本文档旨在记录和总结在 Linux (Ubuntu/Debian-based) 系统上安装 @openai/codex 过程中，因 Node.js 版本和网络环境问题所引发的一系列故障及其最终解决方案。
在系统中安装并配置 @openai/codex 命令行工具。
整个过程可以分为四个主要阶段，每个阶段都遇到了一个关键问题。
@openai/codex 包要求 Node.js 版本 大于或等于 20，而系统当前的 Node.js 版本为 v12.22.9，版本过低，导致安装脚本中的新语法无法被识别。遇到的问题： 安装报错，关键错误信息如下：
npm WARN EBADENGINE Unsupported engine { package: '@openai/[email protected]', required: { node: '>=20' }, current: { node: 'v12.22.9', npm: '8.5.1' } }
SyntaxError: Unexpected token '.'
初始操作：
sudo npm install -g @openai/codex
最终解决方案 2 (手动下载压缩包安装): 这是最稳妥、最不容易受网络波动影响的方法。
# 1. 清理可能存在的失败残留
rm -rf ~/.nvm
# 2. 创建目录，直接下载源码压缩包并解压到指定位置
mkdir -p ~/.nvm && curl -L https://gitee.com/mirrors/nvm-sh/repository/archive/v0.39.7.tar.gz | tar -xz -C ~/.nvm --strip-components=1
# 3. 手动将 nvm 的环境变量配置写入 ~/.bashrc
cat <<'EOF' >> ~/.bashrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
EOF
# 4. 立即激活配置
source ~/.bashrc
# 5. 验证 nvm 是否安装成功
command -v nvm
# 此时应输出 nvm，代表成功
遇到的问题 2 (Git 克隆失败): 虽然安装脚本下载成功了，但在执行过程中再次报错。
error: RPC failed; curl 16 Error in the HTTP2 framing layer
fatal: expected flush after ref listing
Failed to clone nvm repo. Please report this!
分析： 这说明网络环境虽然可以完成短暂的脚本下载，但无法支持 git clone 这种需要持续稳定连接的操作。
解决方案 1 (使用国内镜像源): 改用 Gitee 上的镜像源进行安装。
curl -fsSL https://gitee.com/mirrors/nvm-sh/raw/master/install.sh | bash
遇到的问题 1 (连接失败):
curl: (7) Couldn't connect to server
分析： 这是典型的网络问题，由于众所周知的原因，从国内直接连接 GitHub 的服务器 (raw.githubusercontent.com) 可能会失败。
常规操作 (尝试从 GitHub 安装):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm 在安装 Node.js 之前，需要先连接到 Node.js 的官方服务器 (nodejs.org) 获取可用的版本列表。由于网络问题，这一步也失败了，导致 nvm 认为没有任何版本可供安装。解决方案： 为 nvm 配置国内的 Node.js 镜像源（如淘宝镜像）。
# 1. 设置镜像源，并将其永久写入配置文件，一劳永逸
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node && echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.bashrc
# 2. 重新加载配置 (或者重启终端)
source ~/.bashrc
遇到的问题：
Version '22' not found - try `nvm ls-remote` to browse available versions.
常规操作：
nvm install 22 # 或者其他版本
在解决了所有底层环境和网络问题后，最后的安装就水到渠成了。
最终，安装 Codex (使用 nvm 后，全局安装不再需要 sudo):
npm install -g @openai/codex
此时，安装过程将顺利完成。
验证 Node.js 版本：
node -v # 应输出 v20.x.x 或更高版本
使用配置好镜像的 nvm 安装 Node.js (推荐安装 LTS 长期支持版):
nvm install --lts
下次在新环境配置时，可以直接参考以下核心命令：
安装目标包:
npm install -g @openai/codex
安装 Node.js 并设为默认:
nvm install --lts
nvm use --lts
nvm alias default 'lts/*'
为 NVM 配置国内镜像源:
echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.bashrc
source ~/.bashrc
手动安装 NVM (最稳妥):
rm -rf ~/.nvm
mkdir -p ~/.nvm && curl -L https://gitee.com/mirrors/nvm-sh/repository/archive/v0.39.7.tar.gz | tar -xz -C ~/.nvm --strip-components=1
cat <<'EOF' >> ~/.bashrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
EOF
source ~/.bashrc
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online