Node.js 安装及环境配置教程：Windows / macOS / Linux 安装与 npm 国内镜像加速
更新于
Claude Code、Codex、Gemini CLI、OpenClaw 等命令行工具大多要先装 Node.js。这篇讲清楚哪些情况需要装、该装哪个版本（按各工具 2026 年 10 月的最新要求核对过）、三种系统各自最省事的安装方法、国内下载慢怎么办、以后怎么升级，以及安装后最常见的报错。
node -v 能看到版本号就成功了。先看要不要装
- 需要装：用 npm 安装 Claude Code、Codex CLI，或者使用 Gemini CLI、OpenClaw。
- 可以不装：Claude Code 用官方安装脚本安装时不需要 Node.js（见 Claude Code 配置教程）；只用 Codex 桌面版或 VS Code 插件时也可以跳过 Codex CLI 的安装，但 config.toml 仍然要配。
- 已经装过：终端运行
node -v，版本满足下表就不用重装；版本太低再按下文升级。
装哪个版本
| 工具 | 最低 Node.js 版本 |
|---|---|
| Claude Code（npm 安装） | 22 以上 |
| Gemini CLI | 20 以上 |
| Codex | 16 以上 |
| OpenClaw | 24.x 需 24.22.1 以上，或 26.12.1 以上（不支持 25） |
不确定就装官网标着 LTS 的 24 版本（24.22.1 以上），能同时满足上面所有工具。不要装太老的版本，系统包管理器自带的 Node.js 常常偏旧。
各工具的要求会随新版本变化（OpenClaw 就提高过门槛），上表按 2026-10-23 npm 上的最新版本核对。想自己确认，运行 npm view 包名 engines 就能看到当前要求：
顺带解释一下版本号：Node.js 偶数大版本（22、24、26）会进入 LTS 长期支持，奇数版本（如 25）只维护很短时间。26 目前还是 Current（最新版），Homebrew 的 brew install node 装的就是它；求稳选 24 LTS。
Windows
方法一：官方安装包（最简单）
打开 nodejs.org，下载 LTS 版的 .msi 安装包，一路「下一步」即可，安装程序会自动配置环境变量。
方法二：winget（Windows 10/11 自带）
方法三：Scoop 或 Chocolatey
需要在多个 Node.js 版本之间切换的，可以用 nvm-windows（项目地址 github.com/nvm-windows/nvm）。它和 macOS / Linux 上的 nvm 是两个不同的项目，命令也不一样，以它的说明为准；装它之前先卸载已有的 Node.js。
macOS
方法一：Homebrew（推荐）
想装 24 LTS 用 node@24。它不会自动加入 PATH，装完要按下面加一行（Apple 芯片的 Mac 路径是 /opt/homebrew，Intel 芯片的 Mac 把它换成 /usr/local）：
直接 brew install node 会装最新的 26 版，也能满足上表所有工具，只是不是 LTS。
方法二：官方安装包
在 nodejs.org 下载 macOS 的 .pkg 安装包，双击安装。
Linux（以及想管理多个版本的用户）
推荐：nvm（不需要 sudo，可切换版本）
macOS 也可以用 nvm。Ubuntu / Debian 用 apt install nodejs 装出来的版本通常偏旧，不推荐。
验证安装
前两行能输出版本号（例如 v24.22.1）就说明装好了。第三行显示 npm 全局安装的位置，后面装的 claude、codex、gemini 等命令就放在这里（macOS / Linux 在它下面的 bin 目录，Windows 一般是 %AppData%\npm），找不到命令时会用到。装完一定要新开终端窗口，旧窗口读不到新的环境变量。
国内下载慢怎么办
- npm 安装工具慢：切换到国内镜像
npm config set registry https://registry.npmmirror.com，之后npm install -g ...会快很多。用npm config get registry查看当前用的是哪个源，想恢复官方源用npm config set registry https://registry.npmjs.org。 - nvm 下载 Node.js 慢：先执行
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node，再运行nvm install 24。 - 官方安装包下载慢：可以到 npmmirror 的 Node.js 镜像下载同版本的 .msi / .pkg 安装包，文件和官网一致。
环境配置：npm 全局安装路径和缓存路径（可选）
不少「Node.js 安装及环境配置」教程会让你把 npm 的全局安装目录和缓存目录改到 D 盘。这一步不是必须的：默认设置就能正常使用，只有 C 盘空间紧张、或者想把全局工具集中放在一个目录时才需要改。
npm 的默认位置：全局安装目录在 Windows 上是 %AppData%\npm，在 macOS / Linux 上是 Node.js 安装目录的上一级；缓存在 Windows 上是 %LocalAppData%\npm-cache，在 macOS / Linux 上是 ~/.npm。
Windows 上改到 D 盘的做法（目录名可以自己定）：
改完还要把新的全局目录加进 PATH：打开「系统属性 → 高级 → 环境变量」，在用户变量 Path 里新增 D:\nodejs\node_global。Windows 上全局命令直接装在这个目录里，不在 bin 子目录。原来的 %AppData%\npm 那一项可以删掉，避免新旧两处同时存在。然后新开一个终端，之前装过的全局工具（claude、codex 等）要在新目录里重新安装一次。
~/.npmrc 里已经有 prefix 一行，用 npm config delete prefix 删掉。以后怎么升级
| 当初怎么装的 | 升级方法 |
|---|---|
| 官方安装包 | 下载新版安装包直接覆盖安装 |
| winget | winget upgrade OpenJS.NodeJS.LTS |
| Homebrew | brew upgrade node@24（装的是 node 就用 brew upgrade node） |
| nvm | nvm install --reinstall-packages-from=current 24，会把旧版本里的全局工具一起装到新版本 |
用 nvm 时，每个 Node.js 版本的全局工具是分开的：换了版本后如果提示找不到 claude 或 codex，在新版本下重新 npm install -g 一次即可。
常见问题
提示「node 不是内部或外部命令」或 command not found
环境变量还没生效。关掉所有终端重新打开；仍不行就重启电脑，或重新运行安装包并确认勾选了「Add to PATH」。
node -v 正常，但装好的 claude / codex / gemini 提示找不到命令
npm 全局安装的目录没在 PATH 里。运行 npm prefix -g 看全局目录：macOS / Linux 把它下面的 bin 加进 PATH（写进 ~/.zshrc 或 ~/.bashrc），Windows 确认 %AppData%\npm 在用户环境变量 Path 里，然后重开终端。
安装工具时出现 EBADENGINE / Unsupported engine
Node.js 版本低于这个工具的要求。报错里会写需要的版本，按上文升级后重新安装；也可以用 npm view 包名 engines 先查清楚。
Windows 提示「无法加载文件 npm.ps1，因为在此系统上禁止运行脚本」
这是 PowerShell 的执行策略限制。在 PowerShell 中执行下面这行后重开窗口：
macOS / Linux 全局安装提示 EACCES 权限错误
不要用 sudo 硬装。改用 nvm 安装 Node.js，全局包会装到用户目录，不再需要管理员权限。
npm install 一直卡住或报 ETIMEDOUT
先换国内镜像（见上文）。如果以前给 npm 设过代理，代理失效也会卡住：用 npm config get proxy 和 npm config get https-proxy 查看，不需要就用 npm config delete proxy、npm config delete https-proxy 删掉。
装了新版本，node -v 还是旧版本
电脑上装了多份 Node.js。macOS / Linux 用 which -a node、Windows 用 where node 查看，卸载多余的那份，或统一交给 nvm 管理。