Ubuntu系统使用nvm管理Node.js多版本，版本切换一键搞定（实操完整版）

在Ubuntu开发Node.js项目时，你是否遇到过这样的困扰：不同项目依赖不同的Node.js版本，系统自带的Node版本过旧且无法灵活切换，手动升级/卸载Node还容易出现环境冲突、全局包失效等问题？

今天就给大家分享一套「零冲突、高灵活」的Node.js多版本管理方案——使用nvm（Node Version Manager），全程实操无废话，从环境清理、nvm安装配置，到多版本切换、全局包适配，再到常见问题排查，一次性帮你搞定所有痛点，适合所有Ubuntu开发者（尤其适配bash终端）。

一、为什么选择nvm？（痛点直击）

在介绍实操前，先说说为什么不推荐手动安装/升级Node，以及nvm的核心优势，帮你理解「为什么要这么做」：

• 系统自带Node版本偏旧：Ubuntu软件源中的Node.js版本通常滞后多个版本，无法满足最新项目的依赖需求；

• 版本切换困难：手动安装多个Node版本会导致环境变量冲突，切换版本需要反复修改PATH配置，繁琐且易出错；

• 全局包隔离：不同Node版本对应的npm全局包不兼容，手动管理会出现「安装成功却无法使用」的问题；

• nvm的优势：轻量、无侵入，单独管理每个Node版本，版本切换一键完成，自动隔离全局包，无需修改系统环境变量，卸载也无残留。

重点说明：本文基于Ubuntu 20.04/22.04/24.04（bash终端）实操，其他Ubuntu版本流程一致，无需修改命令。

二、前置准备：清理旧Node环境（避坑关键）

如果你的Ubuntu系统之前安装过Node.js（系统自带或手动安装），建议先彻底清理，避免与nvm管理的版本冲突——这是很多人实操失败的核心原因，一定要认真执行！

2.1 卸载系统自带/手动安装的Node.js和npm

打开终端，依次执行以下命令，卸载旧版本并清理残留：

# 卸载Node.js和npm
sudo apt remove -y nodejs npm

# 清理残留的依赖和配置文件
sudo apt autoremove -y
sudo rm -rf /usr/lib/nodejs /usr/share/nodejs /etc/npmrc

2.2 清理旧的npm全局包和缓存

如果之前配置过npm全局目录（比如~/.npm-global），或者安装过全局包（如opencode-ai、yarn等），也需要一并清理，避免后续冲突：

# 卸载所有全局npm包（可选，若需保留可跳过）
npm uninstall -g $(npm ls -g --depth=0 | awk '/@/ {print $2}' | awk -F@ '{print $1}')

# 清理npm缓存
npm cache clean --force

# 备份并删除旧的npm全局目录（之前配置过prefix的必做）
mv ~/.npm-global ~/.npm-global.bak  # 备份，后续无用可删除

2.3 修复.npmrc配置（核心避坑步骤）

如果之前为了解决npm全局安装权限问题，在~/.npmrc中设置过「prefix」配置，这个配置会和nvm的版本隔离机制冲突，导致nvm切换版本失败，必须删除/注释：

# 编辑~/.npmrc文件
nano ~/.npm-rc

# 找到以下行，删除或在开头加#注释（没有则直接退出）
# prefix=~/.npm-global

# 保存退出：按Ctrl+O，回车确认，再按Ctrl+X

验证：执行cat ~/.npmrc，确保无「prefix」相关配置即可。

三、nvm安装与配置（全程复制命令即可）

清理完旧环境后，开始安装nvm，步骤简单，全程复制命令执行，无需手动修改配置。

3.1 安装nvm依赖

nvm安装需要依赖curl和git（用于从GitHub拉取安装脚本），先确保这两个工具已安装：

sudo apt install -y curl git

3.2 安装最新版nvm

使用nvm官方提供的脚本安装，安全可靠，执行以下命令：

# 安装最新版nvm（官方脚本，实时更新）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

说明：v0.39.7是当前稳定版，若想安装更新版本，可访问nvm官方GitHub（https://github.com/nvm-sh/nvm）获取最新安装命令。

3.3 加载nvm配置（立即生效）

安装完成后，nvm的配置会自动写入~/.bashrc，但当前终端不会立即生效，需要手动加载：

source ~/.bashrc

3.4 验证nvm安装成功

执行以下命令，若输出版本号（如v0.39.7），说明安装成功：

nvm --version

若提示「nvm: 未找到命令」，重启终端后再执行即可（重启后会自动加载~/.bashrc中的配置）。

四、nvm核心使用：多版本Node管理与切换

nvm安装完成后，重点学习核心用法——安装多版本Node、切换版本、设置默认版本，这也是我们使用nvm的核心需求。

4.1 安装多个Node.js版本

推荐安装LTS版本（长期支持版），稳定性更高，适合开发和生产环境。这里以「安装18.x（兼容旧项目）、20.x（主流推荐）、24.x（最新版）」为例：

# 安装18.x LTS版本（hydrogen，兼容旧项目）
nvm install 18

# 安装20.x LTS版本（iron，主流推荐，本文默认首选）
nvm install 20

# （可选）安装24.x LTS版本（krypton，最新版）
nvm install 24

说明：执行命令后，nvm会自动下载对应版本的Node.js和npm，无需手动操作，耐心等待即可。

4.2 查看已安装的Node版本

安装完成后，执行以下命令，查看所有nvm管理的Node版本：

nvm list

正常输出示例（箭头→表示当前正在使用的版本）：

     v18.20.8
->   v20.20.0
     v24.13.0
     system
default -> 20 (-> v20.20.0)

4.3 版本切换（临时+永久）

nvm支持两种切换方式，按需选择，操作简单到离谱：

方式1：临时切换（仅当前终端生效）

适合临时切换版本调试项目，关闭终端后会自动恢复到默认版本：

# 切换到18.x版本
nvm use 18

# 切换到20.x版本
nvm use 20

# 切换到24.x版本
nvm use 24

验证：切换后执行node -v，输出版本号与切换的版本一致即可。

方式2：永久切换（设置默认版本）

设置一个默认版本，后续打开新终端，会自动使用这个版本（推荐设置20.x，主流且稳定）：

# 设置20.x为默认版本
nvm alias default 20

验证：重启终端，执行node -v，输出v20.20.0即生效。

4.4 全局包适配（重点）

注意：nvm会为每个Node版本单独维护全局包目录，切换版本后，之前安装的全局包（如opencode-ai）会失效，需要在对应版本下重新安装：

# 切换到20.x版本（默认版本），安装全局包
nvm use 20
npm i -g opencode-ai  # 示例：安装opencode-ai
npm i -g yarn         # 示例：安装yarn

# （可选）切换到18.x版本，安装全局包（若需在18.x下使用）
nvm use 18
npm i -g opencode-ai yarn

查看当前版本的全局包：npm list -g --depth=0。

五、常见问题排查（踩坑必看）

实操过程中，难免会遇到一些小问题，这里整理了最常见的4个问题，以及对应的解决方案，帮你快速避坑。

问题1：执行nvm use提示「prefix冲突」

报错示例：Your user’s .npmrc file has a globalconfigand/or aprefix setting, which are incompatible with nvm.

解决方案：回到「二、前置准备」的2.3步骤，确保~/.npmrc中无prefix配置，然后执行：

nvm use --delete-prefix v20.20.0  # 替换为你要切换的版本号

问题2：重启终端后，nvm命令提示「未找到」

原因：nvm的配置未写入~/.bashrc，或者写入后未生效。

解决方案：手动添加nvm配置到~/.bashrc：

# 写入nvm配置
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc

# 重新加载配置
source ~/.bashrc

问题3：切换Node版本后，全局包提示「未找到命令」

原因：nvm为每个版本单独维护全局包，切换版本后，之前的全局包不在当前版本的目录下。

解决方案：切换到对应版本后，重新安装该版本需要的全局包（参考4.4步骤）。

问题4：执行nodejs命令，版本与nvm切换的不一致

原因：nodejs是Ubuntu系统自带Node的命令，nvm管理的是node命令，二者不是同一个。

解决方案：日常开发仅使用node和npm命令，不要使用nodejs命令（若已卸载系统版，nodejs命令会提示未找到，属于正常现象）。

六、nvm日常使用高频命令（收藏备用）

整理了日常开发中最常用的nvm命令，一目了然，收藏起来，需要时直接复制：

需求	命令	说明
查看已安装版本	nvm list	列出所有nvm管理的Node版本
临时切换版本	nvm use 版本号（如nvm use 20）	仅当前终端生效
设置默认版本	nvm alias default 版本号	新终端自动生效
安装新版本	nvm install 版本号（如nvm install 22）	默认安装对应LTS版本
卸载版本	nvm uninstall 版本号	卸载不需要的Node版本
查看可安装的LTS版本	nvm ls-remote --lts	列出所有可用的LTS版本
查看当前版本	nvm current	输出当前正在使用的Node版本
清理nvm缓存	nvm cache clear	解决Node安装失败问题

七、总结与实操建议

到这里，Ubuntu系统使用nvm管理Node.js多版本的全套实操就完成了，核心总结一下：

• 核心逻辑：nvm通过隔离不同Node版本的安装目录和全局包目录，实现版本无冲突切换，无需修改系统环境变量；

• 关键步骤：清理旧环境（尤其是prefix配置）→ 安装nvm → 安装多版本Node → 设置默认版本 → 适配全局包；

• 避坑重点：不要混用node和nodejs命令，切换版本后重新安装全局包，避免.npmrc的prefix配置冲突。

实操建议：

1. 无需安装过多版本，保留「常用版本（如20.x）+ 兼容版本（如18.x）」即可，避免占用过多空间；

2. 开发新项目时，优先使用20.x LTS版本，稳定性和兼容性最佳；

3. 若后续需要卸载nvm，只需删除_{/.nvm目录，再删除}/.bashrc中nvm相关配置即可，无任何残留。

按照本文步骤操作，你再也不用为Node.js版本切换、环境冲突而烦恼，轻松实现多项目、多版本的灵活管理，提升开发效率～