Node.js 安装与环境配置指南及教程

# Node.js 环境安装教程（为 CLI 工具做准备）

> **适用对象**：准备用 Codex CLI / Claude Code CLI / Gemini CLI，但机器上还没装 Node.js  
> **来源**：APINebula 文档站「CLI 配置教程 → Node.js 环境安装教程」  
> **目标**：装好 Node.js，并让 `node --version`、`npm --version` 两条命令都能正常输出

---

## 一、这一页在系列里的位置

它不是讲某个客户端怎么填地址的，而是整条链路最前面的**环境准备**。顺序是这样的：

```
0 注册账号 → 1 充值额度 → 2 创建 API 令牌 → 3 装 Node.js（本页） → 4 装 CLI 并填地址
```

装完 Node 之后才是真正碰中转站地址的地方：

| 接下来要去哪          | 要填的东西                                   |
| --------------- | --------------------------------------- |
| Codex CLI       | `~/.codex/config.toml` 里的 `base_url`    |
| Claude Code CLI | `settings.json` 里的 `ANTHROPIC_BASE_URL` |
| Gemini CLI      | 环境变量 `GOOGLE_GEMINI_BASE_URL`           |

**本页全程不涉及任何 API 地址**，所以不存在"替换域名"这一步——地址统一放进附录 B 的对照表里，等你看后面几篇时再对照。

---

## 二、先确认：你到底需不需要装 Node.js

原文开篇说"Claude Code CLI、Codex CLI 和 Gemini CLI 通过 npm 安装，因此需要 Node.js"，方向没错，但**这个前提有例外**，照抄容易白装一套 Node.js。

| 你要用的东西              | 需要 Node.js 吗 | 说明                                   |
| ------------------- | ------------ | ------------------------------------ |
| Claude Code **桌面版** | ❌ 不需要        | 独立安装包，内置运行时                          |
| VS Code **插件**版     | ❌ 不需要        | 跑在 VS Code 的扩展宿主里                    |
| Claude Code **CLI** | ⚠️ 看你走哪条路    | npm 安装需要 ≥22；官方还有**原生安装器**，完全不碰 Node |
| Codex CLI           | ⚠️ 建议装       | npm 安装需要 ≥16；也可以用 Homebrew 或直接下二进制   |
| Gemini CLI          | ✅ **必须**     | 它本身就是个 Node 应用，Node 是它的运行时           |

### 关键区别：Node 在这三个工具里扮演的角色完全不同

这一点原文没写，但它解释了后面所有"版本不够怎么就它一个能跑"的疑问。我查了三个 npm 包的入口文件：

| 工具          | npm 包里的 bin        | Node 的角色                | Node 版本不够会怎样                |
| ----------- | ------------------ | ----------------------- | --------------------------- |
| Claude Code | `bin/claude.exe`   | **只负责安装**：下载对应平台的原生二进制  | 只报一条 `EBADENGINE` 警告，装完照常运行 |
| Codex CLI   | `bin/codex.js`     | 只跑一层很薄的启动器，再拉起 Rust 二进制 | 多数情况能跑                      |
| Gemini CLI  | `bundle/gemini.js` | **就是运行时**，整个程序跑在 Node 上 | 真的起不来                       |

Claude Code 的 npm 包通过 `optionalDependencies` 拉平台分包（`@anthropic-ai/claude-code-win32-x64` 之类），再由 `postinstall` 把二进制链到位。**装完之后 `claude` 命令根本不调用你的 Node**——所以"Node 版本低但 Claude Code 能用"不是玄学。

> **⚠️ 只装 Claude Code 的话，其实可以完全不装 Node**  
> 官方现在提供原生安装器，PowerShell 里一条命令即可，不依赖 Node：
>
> ```powershell
> ```

|   |   |
| - | - |

> irm <https://claude.ai/install.ps1> | iex
>
> ```
> 但 Codex 和 Gemini 没有这条路，所以如果你打算三个都试，装 Node 仍然是最省事的做法。
> ```

---

## 三、版本要求（已核对 npm 上的 `engines` 字段）

原文给的版本线是对的，我拉到三个包的最新版逐个核对，一字不差：

| 工具          | 原文要求             | npm 实际声明     | 当前版本    |
| ----------- | ---------------- | ------------ | ------- |
| Claude Code | Node.js `22` 或更高 | `>=22.0.0` ✅ | 2.1.316 |
| Gemini CLI  | Node.js `20` 或更高 | `>=20` ✅     | 0.66.0  |
| Codex CLI   | Node.js `16` 或更高 | `>=16` ✅     | 0.166.0 |

**结论很简单：装当前 LTS 就同时满足三个。** 截至 2026-11，Node 最新 LTS 是 **v26.13.0（Lithium）**。

> **⚠️ 别照着原文截图里的版本号去找安装包**  
> 截图里是 `v24.15.0`（那张图截于 2026-04，当时确实是 LTS）。Node 每年 4 月和 10 月各发一版，现在 LTS 已经走到 26 了。**认"LTS"这两个字，不要认具体数字。**

---

## 四、步骤 1 · 安装 Node.js

### 4.1 Windows

**① 打开 PowerShell**：按 `Win+R`，输入 `powershell`，回车。

**② 去官网拿安装包**：打开 nodejs.org，点页面正中那个绿色的 `Get Node.js®`。

![](/uploads/editor/20261101/img_6ae617234e11f9.09088276.png)

**③ 选 Windows + 你的架构，下载 `.msi`**。

![](/uploads/editor/20261101/img_6ae617304d10e9.03105836.png)

> **⚠️ 这张示例图其实是 macOS 的**  
> 图上版本行右侧选的是 `macOS`，红框圈住的是 `macOS Installer (.pkg)`。你在 Windows 上要选 `Windows`，然后拿 `Windows Installer (.msi)`（64 位机器选 x64，ARM 机器选 ARM64）。原文把这张图放在「Windows 教程」下面，容易让人以为 Windows 也要下 `.pkg`——`.pkg` 在 Windows 上根本装不了。

**④ 双击 `.msi`，一路 `Next`。** 不确定就保持默认，`Add to PATH` 那一步**不要取消勾选**。

**⑤ 关掉所有 PowerShell 窗口，重新打开一个。** 这一步不是仪式感——Windows 的 PATH 只对新进程生效，老窗口里 `node` 永远找不到。

### 4.2 macOS

1. `Command+Space` 打开聚焦搜索，输入「终端」或 `Terminal`，回车
2. 官网下载 macOS 的 LTS `.pkg`
3. 双击安装，一路继续

`.pkg` 会把 Node 装到 `/usr/local/bin`，普通用户对这个目录没有写权限——**后面 `npm install -g` 可能会要求 `sudo`，先别急着加**，见第八节。

### 4.3 Linux

按发行版走官网给的命令（Debian/Ubuntu 是 NodeSource 源，Fedora 是 `dnf module`，Arch 直接 `pacman -S nodejs npm`）。

> **⚠️ 别用 `apt install nodejs` 装发行版仓库里那个**  
> Ubuntu/Debian 自带的 `nodejs` 包常年停在 18 甚至更早，装上就卡在 Claude Code 的 22 线以下。要么走 NodeSource，要么用 fnm/nvm。

---

## 五、步骤 2 · 验证安装

关掉并**重新打开**终端，然后执行：

```bash
node --version
npm --version
```

两条都打印出版本号，就算装好了。

![](/uploads/editor/20261101/img_6ae618118f6579.33385625.png)

> **⚠️ 这张图有两处要留意，别照抄它的结论**
>
> 1. **它是 macOS 终端**——提示符是 `dvd@mumudeMac-mini ~ %`。Windows 上你会看到 `PS C:\Users\你的用户名>`，两者输出格式不同，别以为装错了。
> 2. **它显示的 `v20.20.0` 不满足文档自己写的 Claude Code 要求（≥22）**。这张图是旧环境截的，只能当"输出长什么样"的参考，不能当"版本够了"的证据。

### 五种结果怎么读

| 你看到的                                   | 含义                        | 怎么办                                 |
| -------------------------------------- | ------------------------- | ----------------------------------- |
| 两个版本号都出来了，Node ≥22                     | 完全就绪                      | 继续装 CLI                             |
| 两个版本号出来了，Node 是 20 或 18                | 能装 Gemini，装不了 Claude Code | 升级到 LTS                             |
| `node : 无法将"node"项识别为 cmdlet…`         | PATH 里没有，或没重开终端           | 先重开终端；仍不行看下面                        |
| `npm : 无法将"npm"项识别为…` 但 `node` 正常      | 只装了 Node 运行时，没装 npm       | 用官方 `.msi`/`.pkg` 重装（自带 npm）        |
| `Unsupported engine` / `EBADENGINE` 警告 | 版本低于包的声明                  | 装 Claude Code 时可以忽略（见第二节），Gemini 不行 |

**`node` 找不到的排查顺序**：① 是不是没重开终端；② `where node`（macOS/Linux 用 `which node`）有没有输出；③ 打开「系统属性 → 环境变量」，看 `Path` 里有没有 Node 的安装目录（默认 `C:\Program Files\nodejs\`）。

---

## 六、步骤 3 · Git Bash（仅 Windows，可选但有代价）

原文说 Git Bash「不是运行这些 CLI 的必需组件」，这句是对的；但它没说的是——**不装不等于没影响**。

按 Claude Code 官方文档的口径：

> Git for Windows is recommended on native Windows so Claude Code can use the Bash tool. **If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead.**

也就是说：**不装 Git Bash，Claude Code 不会坏，但它执行命令时会改用 PowerShell 工具**。跑 `ls`、`grep`、`sed` 这类命令的行为会和你看到的绝大多数教程不一样——那些教程默认你在 Bash 里。所以"可选"是技术上可选，实操上建议装。

### 6.1 下载安装

1. 打开 git-scm.com 的下载页，点 `Click here to download`
2. 运行 `.exe`

![](/uploads/editor/20261101/img_6ae61746c64bf2.55884180.png)

> **想省掉点下载这一步**：同一页面上就写着 winget 命令，PowerShell 里一行装完（版本还更新）：
>
> ```powershell
> winget install --id Git.Git -e --source winget
> ```

### 6.2 安装向导：只有一屏值得看一眼

前面是协议页，直接 `Next`：

![](/uploads/editor/20261101/img_6ae6174f705431.27906912.png)

到 **Select Components** 这屏，默认勾选里有一条 `Add a Git Bash Profile to Windows Terminal`：

![](/uploads/editor/20261101/img_6ae6175885c8d6.93462785.png)

**保持默认就行**，它的作用是往 Windows Terminal 里加一个 Git Bash 配置项，以后从终端下拉菜单就能直接开 Bash。整机大约占 335 MB。

再往后一屏问 SSH 用哪个（`Use bundled OpenSSH` 是默认且推荐的），保持默认点 `Install`：

![](/uploads/editor/20261101/img_6ae617637c4e88.02578515.png)

### 6.3 验证——这一屏是全文最值得看的一张图

![](/uploads/editor/20261101/img_6ae6176e904b32.33946968.png)

这张图完整记录了新手最容易懵的一分钟：

```
PS C:\Users\Administrator> git --version
git : 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。…
PS C:\Users\Administrator> git --version
git version 2.54.0.windows.1
```

**同一个窗口，同一条命令，第一次红字报错，第二次就成功了。** 原因只有一个：中间**新开了一个 PowerShell 窗口**，PATH 重新加载了。

原文把这幅图放上来却一个字没解释，读者很容易以为"装失败了"。记住这条规律：**Windows 上装完任何带 PATH 的东西（Node、Git、Python……），都必须重开终端**；不重开，老窗口里永远是"无法将 X 项识别为…"。

---

## 七、可选 · 需要多个 Node 版本共存

如果你还要维护老项目，或者想在不同 Node 版本间切换，用版本管理器比反复重装干净：

| 系统            | 工具            | 一句话                                   |
| ------------- | ------------- | ------------------------------------- |
| Windows       | `nvm-windows` | 注意：**装它之前要先卸载已装的 Node**，否则两个 PATH 会打架 |
| macOS / Linux | `fnm` 或 `nvm` | fnm 更快，nvm 更老牌                        |

切换后记得**重开终端**再验证——同一条规律。

---

## 八、npm 全局安装的权限问题（macOS / Linux）

后面装 CLI 时会用到 `npm install -g`。在 macOS 上，官方 `.pkg` 装的 Node 位于 `/usr/local`，普通用户没写权限，于是很多人顺手加 `sudo`——**这一步是错的**：

> **Do NOT use `sudo npm install -g`** as this can lead to permission issues and security risks.  
> —— Claude Code 官方安装文档

`sudo npm -g` 会把包和缓存写成 root 所有，之后不带 sudo 就再也装不了东西，清理起来非常麻烦。

**正确做法是把全局目录挪到自己家目录**：

```bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
```

然后把 `~/.npm-global/bin` 加进 `PATH`（写进 `~/.zshrc` 或 `~/.bashrc`），重开终端。之后 `npm install -g` 全程不需要 sudo。

---

## 九、验收清单

装完 CLI 之前，先确认这四条：

- [ ] 新开的终端里 `node --version` 有输出，且 ≥ `v22`
- [ ] `npm --version` 有输出（不是"命令不存在"）
- [ ] `npm config get registry` 是你预期的源（换过国内镜像的话，确认镜像同步了平台分包）
- [ ] Windows 且打算用 Bash 工具：`git --version` 有输出

四条都过，再去装 CLI 并填中转站地址。

---

## 十、常见问题

**Q1：Node 装完了，但 `npm install -g` 报 `EBADENGINE`。**  
只是警告，不是失败。装 Claude Code / Codex 时可以直接忽略（它们是原生二进制，运行时不用你的 Node）；装 Gemini CLI 时不能忽略，那是真跑不起来。

**Q2：`npm install -g` 卡住不动，或者报 `postinstall` 失败。**  
这三个包都靠 `optionalDependencies` 拉平台二进制分包。两种常见原因：

1. **`npm config get omit` 里有 `optional`** → 可选依赖被跳过，二进制根本没下。执行 `npm config delete omit` 后重装。
2. **换了国内镜像**，但镜像没同步 `@anthropic-ai/claude-code-win32-x64` 这类分包 → 临时切回官方源再装。

**Q3：公司电脑不给装 `.msi`，能直接下 zip 吗？**  
能，但 zip 版本不会写 PATH，要手动把解压目录加进环境变量，否则 `node` 一样找不到。不如直接找 IT 要权限。

**Q4：装了两个 Node（一个官网版、一个 nvm 版），`node -v` 显示的版本对不上。**  
PATH 里靠前的那个生效。用 `where node`（Windows）或 `which -a node`（macOS/Linux）看全部路径，把不用的那个从 PATH 里去掉，或者干脆卸掉。

**Q5：Gemini CLI 装完提示 `Node.js version is not supported`。**  
这条最常见于 Ubuntu 用 `apt install nodejs` 装的 18。换成 NodeSource 源或 fnm 装 LTS。

---

## 附录 A · 原文勘误

| #  | 原文写法                                  | 问题                                                           | 本版处理                               |
| -- | ------------------------------------- | ------------------------------------------------------------ | ---------------------------------- |
| 1  | 「验证安装」的截图放在 Windows 小节下               | 图里提示符是 `dvd@mumudeMac-mini ~ %`，是 **macOS 终端**，不是 PowerShell | 明确标注这是 macOS 输出，补 Windows 的提示符样子   |
| 2  | 同一张截图显示 `v20.20.0`                    | 不满足文档自己写的 Claude Code ≥22，读者会以为这个版本就够了                       | 点名"这张图不能当版本够了的证据"                  |
| 3  | Windows 教程里的下载页截图                     | 图里选的是 `macOS` 标签、红框圈着 `macOS Installer (.pkg)`               | 说明这是 macOS 示例，Windows 要选 `.msi`    |
| 4  | 「关闭并重新打开 PowerShell」                  | 没说为什么，也没说报错长什么样                                              | 用第 8 张图的红字解释 PATH 重载               |
| 5  | 未提 Node 在三个工具里的角色不同                   | 读者遇到"版本不够但 Claude Code 能跑"会以为环境坏了                            | 第二节给角色对照表                          |
| 6  | 未提 `EBADENGINE` 只是警告                  | 一看到红色就以为装失败，反复重装                                             | Q1                                 |
| 7  | 未提 npm 必须允许 optional dependencies     | `omit=optional` 时二进制不下载，报错信息与依赖无关                            | Q2                                 |
| 8  | 说 Git Bash「不是必需组件」就结束了                | 漏了代价：不装则 Claude Code 改用 PowerShell 工具，命令行为与教程不一致             | 第六节开头补官方口径                         |
| 9  | 第 8 张图（git 报错→成功）没有任何解释               | 最容易被误读成"装失败了"                                                | 6.3 节逐行解释                          |
| 10 | 未提 winget 安装方式                        | 官网同页就给了 `winget install --id Git.Git`，比点下载快                  | 6.1 节补充                            |
| 11 | 版本号只写"当前 LTS"                         | 截图里的 24.15.0 已不是 LTS，读者会去搜旧版本                                | 第三节给当前 LTS（26.13.0）并说明"认 LTS 不认数字" |
| 12 | macOS 未提 `.pkg` 装到 `/usr/local` 的权限后果 | 读者会顺手 `sudo npm -g`，与官方明确禁止的做法冲突                             | 第八节给 `npm config set prefix` 方案    |
| 13 | 没有验收清单                                | 装完只能靠"感觉好了"                                                  | 第九节四条 checklist                    |
| 14 | Linux 只说"按官网命令"                       | 发行版仓库的 `nodejs` 常年过旧，踩坑率极高                                   | 4.3 节点名 `apt install nodejs` 这个坑   |

---

## 附录 B · 与本系列其它文档的衔接

本页不含任何 API 地址，**没有需要替换的域名**。真正的地址出现在后面三篇，统一按下面的对照填：

| 文档              | 要填的字段                                  | 填什么                                     |
| --------------- | -------------------------------------- | --------------------------------------- |
| Claude Code CLI | `settings.json` → `ANTHROPIC_BASE_URL` | `https://api.zaimod.com`（**不带** `/v1`）   |
| Gemini CLI      | 环境变量 `GOOGLE_GEMINI_BASE_URL`          | `https://api.zaimod.com`（纯域名）            |
| Codex CLI       | `config.toml` → `base_url`             | `https://api.zaimod.com/v1`（**带** `/v1`） |

> **迁移提示**：三个工具对 `/v1` 的处理各不相同（一个不带、一个纯域名、一个带），**这是最容易抄错的地方**——填法取决于"客户端自己会不会补 `/v1`"，不是取决于中转站。照搬同系列另一篇的写法，十有八九会得到 `/v1/v1/...` 的 404。

上一篇：opencode 配置教程{else}上一篇：没有了下一篇：Codex 配置教程{else}下一篇：没有了