这篇把我在 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 --install
Linux ：安装 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@v4
with:
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 nvs
shell: bash
run: |
curl -fsSL https://raw.githubusercontent.com/jasongin/nvs/master/install.sh | bash
. "$HOME/.nvs/nvs.sh"
nvs add lts
nvs link default lts
nvs auto on
- name: Use Node from .node-version
shell: bash
run: |
. "$HOME/.nvs/nvs.sh"
nvs auto on
nvs ls
node -v
corepack 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、原生模块配好编译链与二进制镜像。