适用人群：前端/后端/全栈开发者，Mac/Linux/Windows（nvm-windows）用户；需要在多项目间快速切换 Node 版本、或在国内网络环境下稳定安装 Node。

一、为什么要用 nvm？

一机多版本：不同项目依赖不同 Node 版本（如 16.x / 18.x / 20.x），nvm 可以一条命令切换。
对系统无侵入：不需要 sudo，不污染系统路径，卸载也很干净。
项目级约束：配合 .nvmrc 固定项目 Node 版本，团队一致性更好。
镜像可配：国内可配置镜像源，大幅提升安装速度与成功率。

最佳实践：开发机使用 nvm 管理 Node，避免系统级安装（如 brew install node 或官方 pkg）造成 PATH 冲突。

二、TL;DR 快速开始（Mac/Linux，推荐）

# 1）可选：国内加速（建议先设置）
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
export NVM_IOJS_ORG_MIRROR=https://npmmirror.com/mirrors/iojs# 2）安装 nvm（以 v0.39.7 为例，可改最新稳定版）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 或
#wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash# 3）让当前 Shell 生效（Zsh 常用）
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"# 4）装一个稳定 LTS 版本并使用
nvm install --lts
nvm use --lts
node -v && npm -v

若重开终端后 nvm 不生效，请将 第3步的两行加入 ~/.zshrc 或 ~/.bashrc，并执行 source ~/.zshrc（或重开终端）。

三、安装 nvm（详细版）

3.1 macOS / Linux（官方脚本，推荐）

准备镜像环境（可选但强烈推荐）

echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc
echo 'export NVM_IOJS_ORG_MIRROR=https://npmmirror.com/mirrors/iojs' >> ~/.zshrc
source ~/.zshrc

执行官方安装脚本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 或 wget -qO-

写入 Shell 启动配置（安装脚本通常会自动写入，若未成功手动添加）

# Zsh（macOS 新系统默认）
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc# Bash
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.bashrc
source ~/.bashrc

验证安装
```
command -v nvm
nvm --version
```

3.2 macOS（Homebrew 方式，次选）

说明：nvm 官方推荐脚本安装。若使用 Homebrew，需要手动设置环境变量并创建工作目录。

brew install nvm
mkdir -p ~/.nvm# Apple Silicon（M 系，Homebrew 默认前缀 /opt/homebrew）
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc# Intel Mac（Homebrew 前缀 /usr/local）
# echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
# echo '[ -s "/usr/local/opt/nvm/nvm.sh" ] && . "/usr/local/opt/nvm/nvm.sh"' >> ~/.zshrcsource ~/.zshrc
nvm --version

避免冲突：若机器上曾用 brew install node 或官方 pkg 安装 Node，请先卸载它们（或至少确保 PATH 顺序让 nvm 管理的 Node 优先）。

3.3 Windows（nvm-windows）

Windows 下常用的是 nvm-windows（与 nvm 项目不同代码库，但命令类似）。
安装步骤：
1. 卸载先前用官方 msi 安装的 Node（如已安装）。
2. 下载并安装 nvm-setup（管理员运行）。
3. 安装时选择 nvm 根目录 与 Node 安装目录（默认即可）。
4. 通过命令提示符/PowerShell 使用：
```
nvm version
nvm node_mirror https://npmmirror.com/mirrors/node
nvm npm_mirror https://npmmirror.com/mirrors/npm
nvm install lts
nvm use lts
node -v
```
差异提示：nvm-windows 使用全局 symlink 切换 Node，切换时需要管理员权限的情况更多；.nvmrc 文件不自动生效（可写脚本或使用工具实现）。

四、常用命令速查

# 安装/切换
nvm install <version>           # 例如：nvm install 20.18.0 / nvm install --lts / nvm install node(最新)
nvm use <version>               # 切换到指定版本
nvm alias default <version>     # 设置默认版本（新终端自动使用）
nvm uninstall <version>         # 卸载某版本# 查询
nvm ls                          # 查看本机已安装版本
nvm ls-remote                   # 查看可安装版本（受镜像/网络影响）
nvm current                     # 当前使用版本# 迁移全局包（例如从 16 迁移到 18）
nvm reinstall-packages 16

小技巧：nvm install --lts --latest-npm 可在安装 LTS 的同时升级到较新的 npm（不同版本行为可能略有差异）。

五、项目内固定 Node 版本（`.nvmrc`）

在项目根目录创建 .nvmrc：
```
v18
# 或 18.20.3 / lts/* / v20
```

使用（进入项目目录后）：

nvm use        # 读取 .nvmrc 自动切换
nvm install    # 如未安装会直接安装 .nvmrc 指定的版本

自动切换建议：
- Zsh 用户可使用插件（如 zsh-nvm）或 direnv 在进入目录时自动执行 nvm use。

六、国内网络环境与加速策略

Node 镜像：

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
export NVM_IOJS_ORG_MIRROR=https://npmmirror.com/mirrors/iojs

npm 源（按需）：

npm config set registry https://registry.npmmirror.com
# 恢复官方源：
# npm config set registry https://registry.npmjs.org

代理（公司/校园网）：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

Apple Silicon 注意：优先安装 arm64 对应的 Node 版本，避免 Rosetta 兼容层导致的二进制不匹配。

七、与包管理器协作（npm / pnpm / yarn / corepack）

npm：随 Node 安装，不同 Node 版本对应不同的全局包目录。
pnpm / yarn：
- Node 新版本中内置 Corepack（部分版本需手动启用）：
```
corepack enable
# 指定版本
corepack prepare pnpm@latest --activate
```
- 项目建议使用锁文件（package-lock.json / pnpm-lock.yaml / yarn.lock）保障一致性。
不要在 nvm 场景下修改 npm 全局 prefix 到系统路径，也不要使用 sudo npm -g。

八、常见问题（FAQ）与排查

nvm: command not found
- 是否把下列内容写入了 shell 配置文件（~/.zshrc 或 ~/.bashrc）并 source？
```
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
```
- 是否开启了新终端？是否有安全软件阻拦？
node 版本切换后仍不生效
- 可能 PATH 中仍有系统 Node（如 Homebrew/官方 pkg）优先生效。
- 解决：卸载系统 Node，或确保 nvm 管理的路径在 PATH 前。
安装 Node 速度慢或失败
- 确认镜像变量 NVM_NODEJS_ORG_MIRROR 已设置并生效。
- 公司/学校网络需配置 HTTP/HTTPS 代理。
全局包丢失（切换版本后找不到全局命令）
- 不同 Node 版本的全局包隔离。使用：
```
nvm reinstall-packages <旧版本号>
```
nvm 与 Homebrew 冲突
- 若曾 brew install node，请卸载或保证 nvm 的 node 在 PATH 前。
Windows 下切换失败或权限问题
- 以管理员身份运行 PowerShell；关闭占用 Node 的进程；必要时重启终端。

九、团队协作与 CI 提示

在仓库根目录提供：
- .nvmrc（如 v18）
- 包管理器锁文件（确保依赖可重复安装）
CI（GitHub Actions/GitLab CI）不必安装 nvm，可直接使用官方 setup-node/runner 的 node，但本机开发与 CI 的 Node 版本务必一致（遵循 .nvmrc）。