Node.js 环境搭建与版本管理：用 nvm 把多版本问题一次性解决(2026)

这篇写给谁： 第一次系统搭 Node 环境、或者机器上迟早要同时跑多个 Node 版本的开发者
读完你能做成： 一台机器同时养着多个 Node 版本，进项目目录自动切到对应版本，全程不用 sudo，新机器从零到能干活照着抄一遍脚本就行

如果你只装一个 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 的环境。代价是多一层概念要理解，但对任何会同时碰多个项目的人来说，这层成本几乎是必交的

一个重要的前提：nvm-sh 这个 nvm 是 POSIX shell 脚本，只跑在 macOS / Linux / WSL 上，原生不支持 Windows。 Windows 用户别照搬本文的 curl 命令——后面有专门一节讲 Windows 怎么办

macOS / Linux：安装 nvm

1. 跑官方安装脚本

撰写本文时 nvm 最新是 v0.40.5。直接用官方脚本装(别从某些博客里复制老版本号)：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash

把命令里的 v0.40.5 换成 nvm 仓库 当前的 release tag 更稳妥——版本号是会往前走的，照抄一个写死的旧 tag 是博客类教程最常见的过期点

这个脚本干了两件事：把 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 月，情况是这样：

简单说：做正经项目，装 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 即可。我个人是开了的，体感上「进目录版本就对了」这件事，值得花五分钟配

提醒一句：.nvmrc 只是声明「该用哪个版本」，它不会帮你把那个版本装上。如果本机没装 .nvmrc 里写的版本，nvm use 会报 N/A: version "24" is not yet installed，先 nvm install 一下就好

国内网络：下载慢到超时怎么办

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 / 各命令用法 / 版本号)