如何让npm使用兼容的Node.js版本？GCP Ubuntu实例解决方案

问题背景 #

在GCP的Ubuntu 20.04.6 LTS实例中，克隆GitHub项目后在app目录执行npm时遇到版本不匹配错误：

ERROR: npm v10.1.0 is known not to run on Node.js v10.19.0. This version of npm supports the following node versions: ^18.17.0 || >=20.5.0.

通过二进制包安装了Node.js v20.11.1到/usr/local/lib/nodejs/node-v20.11.1-linux-x64/目录，验证新版本可正常运行：

/usr/local/lib/nodejs/node-v20.11.1-linux-x64/bin/node -v
# 输出：v20.11.1

但系统默认调用的仍是/usr/bin下的旧版本Node.js，直接复制文件到/usr/bin担心引发不一致问题，需找到正确的配置方式让npm使用新版本Node.js。

解决方案 #

方法1：配置环境变量（优先推荐） #

通过将新版本Node.js的bin目录加入系统PATH，让系统优先调用新版本：

• 临时生效（当前会话）：

  export PATH=/usr/local/lib/nodejs/node-v20.11.1-linux-x64/bin:$PATH
  

  执行后验证：

  node -v # 应输出v20.11.1
  npm -v # 对应新版本npm
  

• 永久生效（当前用户）：
  编辑用户bash配置文件：

  nano ~/.bashrc
  

  在文件末尾添加：

  export PATH=/usr/local/lib/nodejs/node-v20.11.1-linux-x64/bin:$PATH
  

  保存退出后，执行以下命令让配置立即生效：

  source ~/.bashrc
  

• 永久生效（所有用户）：
  编辑系统全局配置文件：

  sudo nano /etc/profile
  

  在文件末尾添加同样的PATH配置，保存后执行：

  source /etc/profile
  

方法2：创建软链接到系统默认bin目录 #

不直接复制二进制文件，而是创建软链接，避免文件冗余且便于后续版本切换：

# 可选：备份旧版本的node和npm
sudo mv /usr/bin/node /usr/bin/node_old
sudo mv /usr/bin/npm /usr/bin/npm_old

# 创建新版本的软链接
sudo ln -s /usr/local/lib/nodejs/node-v20.11.1-linux-x64/bin/node /usr/bin/node
sudo ln -s /usr/local/lib/nodejs/node-v20.11.1-linux-x64/bin/npm /usr/bin/npm

验证：

node -v # v20.11.1
npm -v # 对应版本

后续切换版本时，只需删除旧软链接，重新创建对应版本的链接即可。

方法3：使用nvm管理Node.js版本（长期维护推荐） #

nvm是Node.js版本管理器，可轻松切换多个版本，彻底避免版本冲突：

1. 安装nvm：

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

2. 重新加载bash配置：

   source ~/.bashrc
   

3. 安装指定版本Node.js：

   nvm install 20.11.1
   

4. 设置为默认版本：

   nvm alias default 20.11.1
   

验证：

node -v # v20.11.1
npm -v # 对应版本

后续切换版本只需执行nvm use <版本号>，操作便捷。

内容的提问来源于stack exchange，提问作者Bloehdian