适用人群：前端/后端/全栈开发者，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"' >> ~/.zshrc
source ~/.zshrc
nvm --version
避免冲突：若机器上曾用 brew install node 或官方 pkg 安装 Node，请先卸载它们（或至少确保 PATH 顺序让 nvm 管理的 Node 优先）。
3.3 Windows（nvm-windows）Windows 下常用的是 nvm-windows（与 nvm 项目不同代码库，但命令类似）。
安装步骤：
卸载先前用官方 msi 安装的 Node（如已安装）。
下载并安装 nvm-setup（管理员运行）。
安装时选择 nvm 根目录 与 Node 安装目录（默认即可）。
通过命令提示符/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 # 例如：nvm install 20.18.0 / nvm install --lts / nvm install node(最新)
nvm use # 切换到指定版本
nvm alias default # 设置默认版本（新终端自动使用）
nvm uninstall # 卸载某版本
# 查询
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）。
十、最佳实践清单（可直接套用）安装前先设置镜像：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 后，你的多项目协作、版本切换、团队一致性都会显著提升。如果你在安装或切换过程中遇到特殊报错，欢迎在评论区贴出你的系统信息与命令输出，一起排查。