Ubuntu 上配置 Node.js 环境的实用步骤

在 Ubuntu 系统中搭建 Node.js 开发环境，是许多开发者和运维人员的基础操作。选择合适的方法不仅能确保环境稳定，更能提升后续的开发与部署效率。本文将详细介绍几种主流且高效的安装方案，帮助您根据自身需求快速完成配置。

一 安装方式选择

在开始之前，明确您的使用场景至关重要，这将直接决定最佳的安装路径：

• 使用 NodeSource APT 仓库：这是获取较新 LTS 版本或特定版本 Node.js 的首选方法。它提供系统级的稳定安装，经过充分测试，是生产服务器环境的理想选择。
• 使用 NVM（Node Version Manager）：如果您需要在不同项目间灵活切换 Node.js 版本，或者是一名前端或全栈开发者，NVM 是必不可少的工具。它支持在用户目录下安装和管理多个 Node.js 版本，实现无缝切换。
• 使用 Ubuntu 默认仓库：方法最为简单，只需执行 apt install nodejs 即可。但其提供的版本往往较旧，适合用于快速测试、学习或对 Node.js 版本没有严格要求的场景。

三种方案各有优势，您可以根据是部署生产应用还是进行本地开发来做出决策。

二 方式一 NodeSource APT 仓库安装（推荐用于生产）

对于需要高稳定性的生产环境，通过官方推荐的 NodeSource 仓库进行安装是业界普遍采用的最佳实践。具体操作流程如下：

• 更新系统包索引并添加 NodeSource 仓库：以下以安装最新的长期支持（LTS）版本为例。您也可以根据需要替换为特定的大版本号，如 18.x 或 20.x。
  • sudo apt update
  • curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
  • 若需安装特定版本，例如 Node.js 18：curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
• 安装 Node.js 与 npm：此命令会一并安装 Node.js 运行时及其包管理器 npm。sudo apt install -y nodejs
• 验证安装结果：安装完成后，在终端分别运行 node -v 和 npm -v。若能正确显示出版本号，则表明 Node.js 环境已在您的 Ubuntu 系统上成功配置。

三 方式二 使用 NVM 管理多版本（推荐用于开发）

在开发环境中，经常需要为不同的项目适配不同的 Node.js 版本。NVM 为此提供了完美的解决方案，让版本管理变得轻松自如。

• 安装 NVM：通过官方脚本安装是最便捷的方式。以下示例安装 v0.39.7 版本，您可访问其 GitHub 仓库获取最新版本号。
  • curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  • 脚本执行完毕后，必须重新加载 Shell 配置文件以使 nvm 命令生效：source ~/.bashrc（若使用 Zsh shell，则执行 source ~/.zshrc）。
• NVM 常用命令指南：掌握以下几个核心命令，即可高效管理多个 Node.js 版本。
  • 列出所有可远程安装的版本：nvm ls-remote
  • 安装指定版本：nvm install 18.16.1（或直接安装最新的 LTS 版本：nvm install --lts）
  • 设置默认使用的版本（新开终端自动生效）：nvm alias default 18.16.1
  • 在当前终端会话中临时切换版本：nvm use 18.16.1
• 同样，使用 node -v 和 npm -v 来确认当前激活的版本是否正确。

四 配置 npm 与全局包路径

成功安装 Node.js 后，进行一些优化配置可以极大改善使用体验，尤其是在包管理和权限方面。

• 配置 npm 国内镜像源（可选但推荐）：对于国内用户，将 npm 仓库地址切换至国内镜像可以大幅提升依赖包的下载速度。
  • npm config set registry https://registry.npmmirror.com
  • 验证镜像源是否设置成功：npm config get registry
• 安全配置全局包安装路径（避免使用 sudo）：为了避免权限问题并提升安全性，建议将全局包安装到用户主目录下。
  • 创建专属的全局包目录：mkdir ~/.npm-global
  • 配置 npm 使用此目录作为全局安装前缀：npm config set prefix ‘~/.npm-global’
  • 将此目录的二进制路径添加到系统的 PATH 环境变量中：echo ‘export PATH=~/.npm-global/bin:$PATH’ >> ~/.bashrc && source ~/.bashrc
• 安装常用全局工具示例：完成上述配置后，您可以安全地安装一些开发中常用的全局工具，例如：npm install -g yarn pm2 nodemon typescript。

五 快速验证与常见问题

环境配置完成后，运行一个简单的测试应用是验证成功的最佳方式。同时，了解一些常见问题的解决方法，能帮助您快速排错。

• 快速验证：创建一个基础的 Express 服务器：
  • mkdir myapp && cd myapp
  • npm init -y
  • npm install express
  • 新建一个名为 app.js 的文件，并写入以下代码：
    • const express = require(‘express’);
    • const app = express();
    • app.get(‘/’, (req, res) => res.send(‘Hello from Ubuntu Node.js’));
    • app.listen(3000, () => console.log(‘Server running on 3000’));
  • 启动服务器：node app.js；随后在浏览器中访问 https://您的服务器IP地址:3000，如果看到问候信息，则证明 Node.js 环境工作正常。
• 进程守护与管理（生产环境必备）：为确保 Node.js 应用在后台持续稳定运行，推荐使用 PM2 这样的进程管理器。
  • 全局安装 PM2：npm install -g pm2
  • 使用 PM2 启动应用：pm2 start app.js --name “myapp”
  • 设置 PM2 开机自启：首先运行 pm2 startup，然后根据终端输出的提示执行相应的命令。
  • PM2 常用命令：查看应用列表 pm2 list，查看实时日志 pm2 logs，重启指定应用 pm2 restart myapp。
• 常见问题与解决方案：
  • “命令未找到”（Command not found）：这通常是由于环境变量未正确加载。请检查您的 PATH 是否包含了正确的路径（使用 NVM 时，路径类似 ~/.nvm/versions/node/*/bin；使用自定义全局路径时，则是 ~/.npm-global/bin），并重新执行 source ~/.bashrc（或对应的 shell 配置文件）。
  • 服务启动后端口无法访问（尤其在云服务器上）：如果本地能访问但外部无法连接，问题很可能出在服务器的防火墙或安全组规则上。您需要登录云服务商的控制台，在安全组中添加入站规则，放行应用所使用的端口（例如 3000）。也可以临时禁用防火墙进行测试，以定位问题。
  • 多版本 Node.js 并存导致冲突：如果您通过多种方式（如 APT 和 NVM）安装了 Node.js，可能会遇到版本混乱。最佳实践是统一使用 NVM 来管理所有 Node.js 版本，它提供了优秀的版本隔离，能有效避免系统级安装与用户级安装之间的干扰。