Node.js 多版本管理工具 nvm 的安装与使用教程（含镜像加速与常见坑）

适用人群：前端/后端/全栈开发者，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（官方脚本，推荐）

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

   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

2. 执行官方安装脚本

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

3. 写入 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

4. 验证安装

   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"' >> ~/.zshrc

source ~/.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）

1. 在项目根目录创建 .nvmrc：

   v18
   # 或 18.20.3 / lts/* / v20

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

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

3. 自动切换建议：

   • 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）与排查

1. nvm: command not found

   • 是否把下列内容写入了 shell 配置文件（~/.zshrc 或 ~/.bashrc）并 source？

     export NVM_DIR="$HOME/.nvm"
     [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

   • 是否开启了新终端？是否有安全软件阻拦？

2. node 版本切换后仍不生效

   • 可能 PATH 中仍有系统 Node（如 Homebrew/官方 pkg）优先生效。

   • 解决：卸载系统 Node，或确保 nvm 管理的路径在 PATH 前。

3. 安装 Node 速度慢或失败

   • 确认镜像变量 NVM_NODEJS_ORG_MIRROR 已设置并生效。

   • 公司/学校网络需配置 HTTP/HTTPS 代理。

4. 全局包丢失（切换版本后找不到全局命令）

   • 不同 Node 版本的全局包隔离。使用：

     nvm reinstall-packages <旧版本号>

5. nvm 与 Homebrew 冲突

   • 若曾 brew install node，请卸载或保证 nvm 的 node 在 PATH 前。

6. Windows 下切换失败或权限问题

   • 以管理员身份运行 PowerShell；关闭占用 Node 的进程；必要时重启终端。

---

九、团队协作与 CI 提示

• 在仓库根目录提供：

  • .nvmrc（如 v18）

  • 包管理器锁文件（确保依赖可重复安装）

• CI（GitHub Actions/GitLab CI）不必安装 nvm，可直接使用官方 setup-node/runner 的 node，但本机开发与 CI 的 Node 版本务必一致（遵循 .nvmrc）。

---

十、最佳实践清单（可直接套用）

• 安装前先设置镜像：NVM_NODEJS_ORG_MIRROR。

• 统一使用 LTS：nvm install --lts && nvm alias default lts/*。

• 每个项目放一个 .nvmrc，并在进入项目目录后执行 nvm use。

• 不使用 sudo npm -g，需要的 CLI 尽量 npx 或加到 devDependencies。

• 切换大版本后执行 nvm reinstall-packages 迁移常用全局包。

• 避免同时存在系统级 Node 与 nvm Node；若必须共存，确保 PATH 顺序正确。

---

最后小总结

使用 nvm 管理 Node 版本是本地开发环境的"地基工程"。配置好镜像与 .nvmrc 后，你的多项目协作、版本切换、团队一致性都会显著提升。如果你在安装或切换过程中遇到特殊报错，欢迎在评论区贴出你的系统信息与命令输出，一起排查。