Node.js 环境搭建与版本管理：用 nvm 把多版本问题一次性解决(2026)
如果你只装一个 Node，大概率迟早会被它坑一次。
印象最深的一次：本地跑得好好的项目，拉同事的另一个仓库一跑，node-gyp 编译直接挂掉，报一堆看不懂的 C++ 错误。折腾半天才发现，全局是 Node 24，那个老项目锁死在 Node 18，某个 native 依赖在新版本下根本编不过。换个 Node 版本，一切正常。
所以这篇不讲「去官网下个安装包点下一步」，而是直接上 nvm——让你机器上同时躺着好几个 Node 版本，进哪个项目目录就自动切到对应版本。前期多花十分钟，后面省下的是无数个「为什么在我机器上不行」。
先搞清楚：为什么不直接用官网安装包
官网那个 .pkg / .msi 安装包，问题不在于它不好用，而在于它只装一个版本，而且装到系统目录里。后面会带来两个麻烦：
多项目版本打架。一个项目要 Node 18，另一个新项目想用 Node 24 的新特性，官网安装包让你只能二选一，或者每次手动重装。
权限恶心。它装在 /usr/local（或 Windows 的 Program Files），后面 npm install -g 经常报 EACCES 权限错误，逼着你 sudo，而一旦 sudo npm 过，npm 缓存目录权限就被搞乱了，后面更麻烦。
版本管理器（nvm 是其中最流行的）把 Node 装在你自己的家目录下，一个用户态、可随时切换、不需要 sudo 的环境。代价是多一层概念要理解，但对任何会同时碰多个项目的人来说，这层成本几乎是必交的。
macOS / Linux：安装 nvm
1. 跑官方安装脚本
撰写本文时 nvm 最新是 v0.40.5。直接用官方脚本装（别从某些博客里复制老版本号）：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
这个脚本干了两件事：把 nvm 仓库 clone 到 ~/.nvm，然后往你的 shell 配置文件（~/.zshrc、~/.bashrc 之类）里追加几行启动代码。
2. 让当前终端认识 nvm
装完脚本，当前这个终端窗口还不认识 nvm 命令——因为启动代码是写进配置文件了，但还没加载。两个办法：重开一个终端，或者手动 source 一下：
source ~/.zshrc
然后验证：
command -v nvm # 正常会输出: nvm
注意这里不要只用 nvm --version 去验证是否安装成功，command -v nvm 更准——nvm 是个 shell 函数，不是磁盘上的可执行文件，which nvm 有时候反而找不到它，这点经常把人绕进去。
macOS 的一个坑：.zshrc 根本不存在
macOS 从 Catalina（10.15）起默认 shell 换成了 zsh，但系统不会自动给你建 ~/.zshrc。如果你是台干净的新机器，安装脚本会找不到文件可写，启动代码就没真正生效，表现就是「装完了但 nvm 命令死活找不到」。
解决很简单，先手动建一个空文件，再重跑一遍安装脚本：
touch ~/.zshrc
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
装第一个 Node：认准 LTS
环境就绪，装 Node。这里有个版本选择的问题——别上来就装最新版。
Node.js 的版本分两类：LTS（长期支持）和 Current（当前最新）。截至 2026 年 6 月，情况是这样：
| 版本线 | 状态 | 代号 | 适合谁 |
|---|---|---|---|
| Node 24 | Active LTS（当前主力） | Krypton | 生产项目首选 |
| Node 22 | Maintenance LTS（维护期） | Jod | 老项目维持 |
| Node 26 | Current（尝鲜） | —— | 想试新特性、非生产 |
简单说：做正经项目，装 Active LTS（现在是 24）。Current 线（26）拿到的是最新特性，但稳定性和生态兼容性还在爬坡，native 依赖、各种工具链未必都跟上，不适合压生产。
补一句背景：Node.js 团队在 2026 年宣布了发布节奏的调整，从 Node 27 起改成每年 4 月一个大版本、10 月全部转 LTS，不再有奇偶版本之分。但这不影响你现在的选择——认准当前标着 Active LTS 的那条线就对了。
用 nvm 装 LTS，一条命令：
nvm install --lts
它会自动找到当前最新的 LTS（也就是 24.x），下载、安装，并把当前终端切过去。装完看一眼：
node -v # v24.x.x
npm -v # 对应的 npm 版本
如果你确实需要某个特定大版本，直接点名：
nvm install 22 # 装最新的 22.x
nvm install 18.20.4 # 装精确到补丁号的版本
日常多版本切换的几条命令
把这几条记住，基本就够用了：
nvm ls # 看本机装了哪些版本，以及当前用的是哪个
nvm ls-remote # 看远程能装哪些版本（很长，可以 grep 一下）
nvm use 22 # 当前终端切到 22
nvm install --lts # 装/更新到最新 LTS
有个反复会咬人的点：nvm use 只对当前这个终端窗口生效，而且重开终端就失效了。你切到 22 写了一下午，明天早上新开终端，它又回到默认版本去了。
所以你需要设一个默认版本，让每个新终端启动就用它：
nvm alias default 24 # 默认用 24
# 或者永远跟随最新已安装版本：
nvm alias default node
真正解放双手：用 .nvmrc 让项目自动切版本
手动 nvm use 时间长了一定会忘。更省心的做法是给每个项目根目录放一个 .nvmrc 文件，把这个项目要的 Node 版本写进去，提交到 git。这样团队里任何人 clone 下来，都知道该用哪个版本。
# 在项目根目录
echo "lts/*" > .nvmrc # 跟随最新 LTS
# 或者锁死大版本，更适合生产项目：
echo "24" > .nvmrc
之后进到这个目录，直接 nvm use（不带版本号），nvm 会自己读 .nvmrc：
cd my-project
nvm use
# Found '.../my-project/.nvmrc' with version <24>
# Now using node v24.x.x
到这一步还得手动敲 nvm use。想做到 cd 进目录就自动切换，得在 shell 配置里加一段钩子函数——nvm 官方 README 的「Deeper Shell Integration」一节给了 bash / zsh / fish 各自的现成脚本，把对应那段贴进 ~/.zshrc 即可。经验表明，开了之后体感上「进目录版本就对了」这件事，值得花五分钟配。
国内网络：下载慢到超时怎么办
nvm install 卡在下载、或者直接超时，十有八九是网络问题——Node 的二进制默认从 nodejs.org 拉。可以让 nvm 走国内镜像：
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
把这行加进 ~/.zshrc，之后 nvm install / nvm ls-remote 都会走这个镜像。这只解决「装 Node 本身」的速度；装 npm 包慢是另一码事，那个要单独配 npm 的 registry：
npm config set registry https://registry.npmmirror.com
两者别搞混——见过有人配了 npm 镜像还在抱怨 nvm install 慢，根本是两条不相干的下载通道。
几个会让你 debug 半天的真实坑
1. 之前用 Homebrew 装过 node，现在跟 nvm 打架
典型症状：nvm use 明明切了版本，node -v 却纹丝不动，或者 which node 指向 /opt/homebrew/bin/node 而不是 ~/.nvm/...。原因是 Homebrew 的 node 在 PATH 里排在 nvm 前面，把 nvm 的盖住了。干净做法是先卸掉 Homebrew 的 node：
brew uninstall --ignore-dependencies node
然后重开终端，which node 应该指回 .nvm 目录里。一台机器上只让一个东西管 Node，别 Homebrew 和 nvm 混着来。
2. 全局包（npm i -g）切版本后「消失」了
这不是 bug，是设计如此：nvm 下每个 Node 版本有各自独立的全局包目录。你在 Node 18 下 npm i -g pnpm，切到 Node 24 后它当然不在。装新版本时想把旧版本的全局包一起带过来，用这个：
nvm install 24 --reinstall-packages-from=18
3. VS Code 内置终端里 nvm 用不了 / 版本不对
集成终端有时不是登录 shell，加载配置文件的方式跟你平时开的终端不一样，导致 nvm 没被 source。在 VS Code 设置里把 terminal.integrated.defaultProfile 指向你日常用的 shell，或者确认它以 login shell 启动，基本能解决。
Windows 用户怎么办
前面说过，nvm-sh 不支持 Windows。Windows 上有两个主流替代：
- nvm-windows（coreybutler/nvm-windows）：名字像、命令也像，但是另一个独立项目，不是同一个 nvm。它有自己的安装器（去 GitHub releases 下
nvm-setup.exe），命令大体相通（nvm install、nvm use），但不认.nvmrc，镜像配置方式也不一样。别拿本文的curl脚本去 Windows 上跑，跑不通。 - fnm（Fast Node Manager）：Rust 写的，跨平台（Windows / macOS / Linux 都行），启动比 nvm 快不少，而且原生支持
.nvmrc和.node-version、能做cd自动切换。如果你是 Windows、或者嫌 nvm 每次开终端慢，fnm 是很值得一换的选择，命令风格跟 nvm 很接近，迁移成本低。
WSL（Windows Subsystem for Linux）里则可以直接用本文的 nvm-sh，跟 Linux 完全一致——如果你 Windows 上的开发本来就在 WSL 里跑，那就当 Linux 处理。
收尾：一套能直接抄的初始化流程
新机器从零到能干活，顺序是这样：
# 1. (macOS 新机器先确保配置文件存在)
touch ~/.zshrc
# 2. 装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
source ~/.zshrc
# 3. 装当前 LTS 并设为默认
nvm install --lts
nvm alias default 'lts/*'
# 4. (国内)配镜像
echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc
npm config set registry https://registry.npmmirror.com
# 5. 进项目用 .nvmrc 锁版本
cd your-project
echo "24" > .nvmrc
nvm use
到这儿，你的机器已经能同时养着任意多个 Node 版本，按项目自动切换，而且全程不用 sudo。下次再遇到「这项目要老版本 Node」的时候，nvm install 一下、.nvmrc 写一行，就过去了——不用再像开头那样，为一个 native 依赖的编译错误折腾一下午。
你平时是用 nvm、fnm，还是 Homebrew / 官网包直接装？有没有踩过版本切换的坑，评论区聊聊。
参考来源
- Node.js — Previous Releases（版本线 / LTS 状态，采集于 2026-06）
- Node.js Moves to One Major Release Per Year, Starting with Node 27（InfoQ）（发布节奏调整）
- nvm-sh/nvm 官方 README（安装命令 /
.nvmrc/ 各命令用法 / 版本号）
