NVM安装介绍

NVM 安装、Node.js 多版本管理、项目版本锁定和常见问题处理。

NVM

NVM（Node Version Manager）用于在同一台机器上安装、切换和管理多个 Node.js 版本。它适合本地开发、构建机、临时排障环境和需要维护多个前端项目的运维场景。

适用场景

不同项目依赖不同 Node.js 主版本。
本地需要快速验证 Node.js 版本兼容性。
CI/CD 构建环境需要按项目指定版本执行构建。
需要在不影响系统 Node.js 的情况下安装临时版本。
需要统一团队项目的 Node.js 使用版本。

安装 NVM

官方安装方式通常是执行安装脚本。安装脚本版本号会随 NVM 发布更新，实际使用时建议以官方仓库 README 中的版本为准。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

如果使用的是 zsh，安装后确认 ~/.zshrc 中存在以下内容：

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

重新加载 shell 配置：

source ~/.zshrc

验证 NVM 是否可用：

nvm --version

安装 Node.js

安装最新 LTS 版本：

nvm install --lts

安装指定版本：

nvm install 20
nvm install 20.11.1

查看本机已安装版本：

nvm ls

查看远端可安装版本：

nvm ls-remote

切换当前 shell 使用的 Node.js 版本：

nvm use 20

设置默认 Node.js 版本：

nvm alias default 20

验证当前版本：

node -v
npm -v
which node

项目版本锁定

在项目根目录创建 .nvmrc：

进入项目后执行：

nvm use

如果本机没有安装 .nvmrc 中声明的版本：

nvm install
nvm use

常见项目启动流程：

cd /path/to/project
nvm use
npm install
npm run dev

国内网络环境

如果访问 Node.js 官方下载源较慢，可以配置镜像源：

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvm install 20

如需长期生效，可写入 ~/.zshrc：

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

然后重新加载配置：

source ~/.zshrc

常用命令

命令	说明
`nvm --version`	查看 NVM 版本
`nvm install --lts`	安装最新 LTS Node.js
`nvm install 20`	安装 Node.js 20
`nvm use 20`	切换到 Node.js 20
`nvm alias default 20`	设置默认 Node.js 版本
`nvm ls`	查看本机已安装版本
`nvm ls-remote`	查看远端可安装版本
`nvm current`	查看当前 shell 使用版本
`nvm uninstall 18`	删除指定版本

CI/CD 使用建议

在 CI/CD 中不建议依赖交互式 shell 自动加载 NVM，建议显式加载：

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

nvm install
nvm use
npm ci
npm run build

如果构建机频繁执行构建，可以预先安装常用 Node.js 版本，减少每次流水线下载耗时。

常见问题

nvm: command not found

通常是 shell 配置没有加载 NVM。

检查当前 shell：

echo $SHELL

检查配置文件：

grep NVM_DIR ~/.zshrc
grep NVM_DIR ~/.bashrc

重新加载：

source ~/.zshrc

node 版本切换后没有生效

检查当前 node 来源：

which node
node -v
nvm current

如果 which node 指向系统路径或 Homebrew 路径，说明当前 shell 没有优先使用 NVM 管理的 Node.js。

npm 全局包丢失

不同 Node.js 版本的全局包是隔离的。切换 Node.js 版本后，需要重新安装对应版本下的全局包。

nvm use 20
npm list -g --depth=0
npm install -g pnpm

权限问题

NVM 安装的 Node.js 默认位于用户目录下，通常不需要 sudo。如果安装 npm 包时遇到权限问题，优先检查是否误用了系统 Node.js。

which node
which npm
npm config get prefix

卸载 NVM

删除 NVM 目录：

rm -rf ~/.nvm

从 shell 配置中删除 NVM 相关内容：

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

重新加载 shell：

source ~/.zshrc

关联文档

自动化构建中的 Node.js 版本管理。
前端项目 .nvmrc 规范。
CI/CD 构建机 Node.js 缓存策略。