Node.js 多版本管理与 nvm/nvs 使用全流程（含国内镜像加速与常见坑）
这篇把我在 Windows / macOS / Linux 上折腾 Node 多版本的经验一次讲清：选谁、怎么装、怎么配镜像、如何团队统一、以及哪些坑必须提前绕开。
目标：本地 15 分钟开箱、团队版本统一不吵架、CI 可重复构建。
目录
结论先说在前（如何选 nvm / nvs）
基础知识：LTS / Current、Corepack 与包管理器
macOS / Linux：nvm 安装与镜像加速
Windows 两种路线：nvs（推荐）与 nvm-windows
nvs 跨平台统一实践（命令大全 + 镜像配置）
国内镜像与二进制依赖加速（npm / 头文件 / 常见原生模块）
团队协作与 CI：.nvmrc / .node-version / Corepack / Actions 模板
高频踩坑与排错清单
速查表（Cheat Sheet）与卸载/升级
1) 结论先说在前
你只有 macOS/Linux？ 用 nvm，生态成熟、教程最多。
你跨平台（Windows + macOS + Linux）且想“一套命令走天下”？ 用 nvs（Node Version Switcher），一个工具全平台统一，特别适合团队规范。
公司里 Windows 居多但不想换命令习惯？ 也可用 nvm-windows，但与 nvm 有细微差异；跨平台一致性更推荐 nvs。
版本策略（我用的默认）
业务主线：LTS（例如
lts/iron、lts/*、具体版本号如20.16.0）。新功能试水或工具链：装一份 Current，但不设为默认。
项目根放一个
.nvmrc（或.node-version）锁住 Node 版本，CI 用同一版本。包管理器版本由 Corepack 固化（
packageManager字段 +corepack enable）。
2) 基础知识：LTS / Current、Corepack 与包管器
LTS vs Current：LTS 优先稳定与长期维护；Current 更快，适合尝鲜或局部用途。
ABI 与原生模块：切换 Node 版本可能触发原生模块重编译（如
sharp、node-sass）。Corepack：Node 16.10+ 自带，用来锁定 npm/yarn/pnpm 版本。
在
package.json写明包管器版本：{ "packageManager": "pnpm@9.0.0" } // 或 npm@10.x / yarn@4.x启用：
corepack enable #（必要时）corepack prepare pnpm@9.0.0 --activate
3) macOS / Linux：nvm 安装与镜像加速
3.1 安装 nvm
# 安装（zsh/bash均可）
export NVM_DIR="$HOME/.nvm"
# 官方安装脚本（示例）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash# 让当前终端生效（或重开终端）
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
建议把以上两行
export+source添到~/.zshrc或~/.bashrc，避免重启丢环境。
3.2 国内镜像（加速下载 Node 分发包）
nvm 支持通过环境变量替换下载源（Node 官方分发地址镜像）：
# 清华/npmmirror 均可，下行示例使用 npmmirror
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
# 若需 io.js（历史包），也可：export NVM_IOJS_ORG_MIRROR=...
3.3 常用命令
nvm install --lts # 安装最新 LTS
nvm install 20.16.0 # 安装指定版本
nvm use 20 # 切到主版本 20（或完整号）
nvm alias default 20.16.0 # 设为默认版本
nvm ls # 列本机已装
nvm ls-remote --lts # 列可安装的 LTS
nvm uninstall 18.19.1 # 卸载某版本
3.4 项目级自动切换（.nvmrc）
项目根新建 .nvmrc（内容仅一行版本号）：
20.16.0
进入项目目录后执行：
nvm use # 自动读取 .nvmrc
若想“进入目录自动切”，可以配合
direnv/avn之类工具，但不是 nvm 核心功能，按需选择。
4) Windows 两种路线：nvs（推荐）与 nvm-windows
4.1 路线 A：nvs（跨平台统一，推荐）
安装（PowerShell）：
# 管理员或用户 PowerShell 均可 iwr https://raw.githubusercontent.com/jasongin/nvs/master/install.ps1 -UseBasicParsing | iex # 安装完成后重开终端，确保 nvs 在 PATH 中镜像（加速 Node 分发包）
方式一：环境变量[Environment]::SetEnvironmentVariable("NVS_NODEJS_ORG_MIRROR","https://npmmirror.com/mirrors/node","User")方式二：配置远程源（见第 5 节）。
4.2 路线 B：nvm-windows（兼容性好，生态广）
安装
nvm-setup.exe（常见做法）。镜像：编辑
%NVM_HOME%\settings.txt（安装时会显示路径），加入/修改：node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/常用命令（与 nvm 类似但实现不同）：
nvm install 20.16.0 nvm use 20.16.0 nvm ls nvm uninstall 18.19.1
注意：不要在同一台 Windows 上同时装 nvs 和 nvm-windows，容易 PATH 冲突；选一个即可。
5) nvs 跨平台统一实践（命令大全 + 镜像配置）
我更偏爱 nvs，因为三端命令一致，团队写文档/脚本不必分平台。
5.1 基本命令
nvs ls # 查看本机已装
nvs ls-remote # 查看可安装列表
nvs add lts # 安装最新 LTS
nvs add 20.16.0 # 安装指定版本
nvs use lts # 临时切换当前 shell
nvs link default 20.16.0 # 设为默认版本（新 shell 生效）
nvs rm 18.19.1 # 卸载
nvs which 20.16.0 # 某版本可执行路径
nvs exec 20.16.0 node -v # 用指定版本临时执行命令
5.2 自动切换（项目级）
nvs 支持自动切换（按目录检测版本文件或 package.json 的 engines）：
nvs auto on # 开启自动切换
nvs auto off # 关闭
在项目根放 .node-version 或 .nvmrc，或在 package.json 写 engines.node，进入目录会自动切版本。
5.3 镜像配置（两种方式）
方式一：改远程源
# 查看已配置的远程源 nvs remote# 把名为 node 的远程源指向国内镜像（Node 官方分发包） nvs remote node https://npmmirror.com/mirrors/node方式二：环境变量
与上节相同：NVS_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
6) 国内镜像与二进制依赖加速（npm / 头文件 / 常见原生模块）
多版本管理解决“切版本”，镜像解决“下不动”。
6.1 npm/yarn/pnpm 源
项目根 .npmrc（推荐）：
registry=https://registry.npmmirror.com
# Node 头文件下载镜像（node-gyp 会用到）
disturl=https://npmmirror.com/mirrors/node/
（Yarn Berry 在 .yarnrc.yml 设置 npmRegistryServer；pnpm 同样读取 .npmrc 或 .pnpmrc。）
6.2 常见原生模块的二进制镜像（按需添加）
# Electron
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
# Puppeteer/Chromium
PUPPETEER_DOWNLOAD_HOST=https://npmmirror.com/mirrors
# sharp/libvips
SHARP_DIST_BASE_URL=https://npmmirror.com/mirrors/sharp-libvips
# node-sass（若仍使用）
SASS_BINARY_SITE=https://npmmirror.com/mirrors/node-sass
6.3 node-gyp 编译链（避免 ELIFECYCLE）
macOS：
xcode-select --installLinux：安装
python3 make gcc g++（如build-essential）Windows：安装 Visual Studio Build Tools（含“使用 C++ 的桌面开发”）或：
npm i -g windows-build-tools #（较旧方案，按需）
7) 团队协作与 CI：.nvmrc / .node-version / Corepack / Actions 模板
7.1 项目内锁定版本（两种选择）
.nvmrc内容：20.16.0.node-version内容同上。
我习惯 两者放一个即可，nvs/nvm 都能识别；再配合
package.json的engines.node双保险。
7.2 锁定包管理器版本（Corepack）
package.json：
{"packageManager": "pnpm@9.0.0","engines": { "node": ">=20.16.0 <21" }
}
初始化一次：
corepack enable
# 可选：corepack prepare pnpm@9.0.0 --activate
7.3 GitHub Actions（示例）
用 actions/setup-node（最简单，适用于 nvm/nvs 皆可）
- uses: actions/setup-node@v4with:node-version-file: '.nvmrc' # 或 '.node-version'cache: 'pnpm' # npm/yarn/pnpm 任选其一
- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm -r build
显式使用 nvs（跨平台脚本统一）
- name: Install nvsshell: bashrun: |curl -fsSL https://raw.githubusercontent.com/jasongin/nvs/master/install.sh | bash. "$HOME/.nvs/nvs.sh"nvs add ltsnvs link default ltsnvs auto on- name: Use Node from .node-versionshell: bashrun: |. "$HOME/.nvs/nvs.sh"nvs auto onnvs lsnode -vcorepack enable
8) 高频踩坑与排错清单
同时装了 nvm、nvs、nvm-windows，PATH 乱了
现象：版本切换无效、
node -v不变。做法：只保留一个管理器；清理其他工具写入的 PATH（macOS/Linux 在
~/.zshrc/~/.bashrc，Windows 在“系统环境变量”）。
nvm 没生效
现象：
nvm: command not found或node还是系统版本。做法：确认
NVM_DIR的两行source已写进 shell 配置并source了；zsh 用户别忘了写~/.zshrc。
Windows 切版本后某些 IDE 仍旧指向旧 Node
现象：IDE 内置终端与外部终端
node -v不一致。做法：重启 IDE/终端；检查 IDE 的 Node 路径设置；确认 nvs/nvm-windows 的“符号链接目录”在 PATH 前列。
原生模块频繁重编译 / 安装超时
现象：切版本或 CI 安装变慢、ELIFECYCLE 错误。
做法：按第 6 节配好
disturl与二进制镜像；完善编译链（Windows 装 VS Build Tools）。
公司代理/防火墙导致安装失败
现象：curl 脚本超时、下载中断。
做法：用 国内镜像（第 3、5、6 节）；必要时设置 HTTP(S)_PROXY；或在内网搭 Nginx 反代。
Apple Silicon 与 x64 混用
现象：Rosetta 与原生架构切换，某些二进制包架构不匹配。
做法：统一架构（尽量用 arm64 原生）；必要时用
arch -x86_64 zsh临时开启 Rosetta 环境安装对应版本。
CI 与本地 Node 版本不一致
现象：本地 OK，CI 挂。
做法：统一用
.nvmrc/.node-version；Actions 用setup-node读取文件；锁定包管器版本。
9) 速查表（Cheat Sheet）
nvm（macOS/Linux）
nvm install --lts
nvm install 20.16.0
nvm use 20
nvm alias default 20.16.0
nvm ls
nvm ls-remote --lts
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvs（跨平台）
# 安装（macOS/Linux）
curl -fsSL https://raw.githubusercontent.com/jasongin/nvs/master/install.sh | bash
. "$HOME/.nvs/nvs.sh"# 安装（Windows PowerShell）
iwr https://raw.githubusercontent.com/jasongin/nvs/master/install.ps1 -UseBasicParsing | iex# 使用
nvs add lts
nvs add 20.16.0
nvs use lts
nvs link default 20.16.0
nvs auto on
nvs remote node https://npmmirror.com/mirrors/node # 镜像
npm / 包管理器与镜像
# .npmrc（项目根）
registry=https://registry.npmmirror.com
disturl=https://npmmirror.com/mirrors/node/
corepack enable
# package.json: { "packageManager": "pnpm@9.0.0" }
卸载与升级
nvm：删除
~/.nvm目录并清理 shell 配置中加载语句；或直接覆盖升级到更高版本脚本。nvs：删除
~/.nvs（*nix）或用户目录下.nvs（Windows）；重新执行安装脚本即可升级。nvm-windows：控制面板卸载，删除
%NVM_HOME%和%NVM_SYMLINK%残留目录，清理 PATH。
小结语
nvm：类 Unix 环境首选，成熟稳妥；
nvs：跨平台一致性最佳，团队文档/脚本可统一；
镜像：
NVM_NODEJS_ORG_MIRROR / NVS_NODEJS_ORG_MIRROR + npm registry配好，基本告别“下不动”；团队与 CI：
.nvmrc/.node-version + Corepack + setup-node，版本锁死，构建可重复；踩坑：三套版本管理器不要共存、Windows 记得重启 IDE、原生模块配好编译链与二进制镜像。