PM2 环境搭建、安装与运维手册

适用环境：Ubuntu 22.04 (Jammy) 服务器 · Node.js 18+（推荐 20 LTS）· PM2 7.x
内容范围：从零安装 Node、安装 PM2，到生产环境进程管理、开机自启、日志与故障排查。

摘要：PM2 是 Node.js 最常用的生产级进程管理器，可实现崩溃自动重启、多核集群、日志集中与开机自启。本文基于 Ubuntu 22.04 实机操作整理，包含 apt 源 403、libnode-dev 冲突、EBADENGINE 等常见问题的解决办法，适合运维与后端开发者收藏查阅。

目录

1. PM2 简介
2. 环境要求
3. 服务器基础准备
4. 安装 Node.js
5. 安装 PM2
6. 快速上手
7. 配置文件 ecosystem
8. 进程管理命令
9. 日志管理
10. 集群与性能
11. 开机自启
12. 环境变量与多环境
13. 部署与更新
14. 监控与告警
15. 日常运维清单
16. 故障排查
17. 附录：命令速查表

1. PM2 简介

PM2（Process Manager 2）是 Node.js 应用的生产级进程管理器，主要能力包括：

典型使用场景：Express / Koa / Nest API、Next.js 服务、定时任务脚本、WebSocket 服务等。

2. 环境要求

注意：Ubuntu 22.04 默认 apt install nodejs 为 v12，无法满足 PM2 7，必须通过 NodeSource 或 nvm 升级。

3. 服务器基础准备

3.1 修复 apt 软件源（可选）

若 apt update 出现 cn.archive.ubuntu.com 403 Forbidden 或 no longer signed：

# 将中国镜像替换为官方源

sudo sed -i 's/cn.archive.ubuntu.com/archive.ubuntu.com/g' /etc/apt/sources.list
sudo sed -i 's/cn.archive.ubuntu.com/archive.ubuntu.com/g' /etc/apt/sources.list.d/*.list 2>/dev/null

sudo apt update

若出现 configured multiple times 警告：打开 /etc/apt/sources.list，删除文件末尾重复的三行 deb http://archive.ubuntu.com/ubuntu/ jammy ...，再执行 sudo apt update。

3.2 安装基础工具

sudo apt update
sudo apt install -y curl git build-essential

4. 安装 Node.js

4.1 方式一：NodeSource（推荐，适合服务器）

# 添加 Node.js 20 LTS 源

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# 若系统已有 Ubuntu 自带 Node 12，先卸载冲突包

sudo apt remove -y nodejs libnode-dev npm
sudo apt autoremove -y

# 安装并验证

sudo apt install -y nodejs
node -v   # 期望 v20.x.x
npm -v

常见错误：trying to overwrite '/usr/include/node/common.gypi'
原因：libnode-dev（Node 12 开发包）与 NodeSource 的 nodejs 冲突。
处理：

sudo apt remove -y nodejs libnode-dev npm
sudo apt autoremove -y
sudo dpkg --configure -a
sudo apt install -y nodejs

4.2 方式二：nvm（适合多版本、开发机）

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

nvm install 20
nvm use 20
nvm alias default 20
node -v

使用 nvm 时，全局 npm install -g pm2 无需 sudo。

4.3 国内 npm 镜像（可选）

npm config set registry https://registry.npmmirror.com

# 恢复官方源：npm config delete registry

5. 安装 PM2

5.1 全局安装

sudo npm install pm2 -g
pm2 -v

首次运行会输出 PM2 标识并启动守护进程，例如版本 7.0.1。

5.2 安装成功标志

• 无 EBADENGINE 警告（Node ≥ 18）
• 输出 [PM2] PM2 Successfully daemonized
• pm2 -v 能显示版本号

5.3 仍提示 Node 版本过低时

which node
which pm2
node -v

确保 node 指向 v20 路径（如 /usr/bin/node），然后重新登录 SSH 或执行 hash -r。

6. 快速上手

6.1 启动单个应用

cd /var/www/myapp
pm2 start app.js --name myapp

# 或通过 npm 脚本启动

pm2 start npm --name myapp -- start

6.2 常用查看命令

pm2 list          # 进程列表
pm2 show myapp    # 详细信息
pm2 logs myapp    # 实时日志
pm2 monit         # 终端监控面板

6.3 停止与删除

pm2 stop myapp
pm2 restart myapp
pm2 delete myapp

7. 配置文件 ecosystem

生产环境强烈建议使用 ecosystem.config.js，便于版本管理与复现。

7.1 单应用示例

module.exports = {
  apps: [
    {
      name: 'myapp',
      script: './dist/main.js',
      cwd: '/var/www/myapp',
      instances: 1,
      exec_mode: 'fork',
      watch: false,
      max_memory_restart: '500M',
      env: {
        NODE_ENV: 'development',
        PORT: 3000,
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
      error_file: './logs/err.log',
      out_file: './logs/out.log',
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
      merge_logs: true,
      autorestart: true,
      max_restarts: 10,
      min_uptime: '10s',
    },
  ],
};

pm2 start ecosystem.config.js
pm2 start ecosystem.config.js --env production

7.2 多应用示例

module.exports = {
  apps: [
    { name: 'api', script: './api/server.js', instances: 2, exec_mode: 'cluster' },
    { name: 'worker', script: './worker.js', instances: 1, exec_mode: 'fork' },
  ],
};

8. 进程管理命令

8.1 生命周期

8.2 批量操作

pm2 restart all
pm2 reload all
pm2 stop all
pm2 delete all

8.3 保存与恢复

pm2 save        # 保存进程列表
pm2 resurrect   # 从 dump 恢复
pm2 cleardump   # 清空保存的列表

9. 日志管理

9.1 查看日志

pm2 logs
pm2 logs myapp --lines 200
pm2 logs myapp --err

9.2 日志路径

默认目录：~/.pm2/logs/（如 myapp-out.log、myapp-error.log）。

9.3 日志轮转（防磁盘占满）

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 14
pm2 set pm2-logrotate:compress true

9.4 清空日志

pm2 flush

10. 集群与性能

10.1 集群模式

pm2 start app.js -i 4
pm2 start app.js -i max

{
  name: 'api',
  script: './server.js',
  instances: 'max',
  exec_mode: 'cluster',
}

10.2 fork 与 cluster

10.3 内存超限自动重启

max_memory_restart: '512M',

11. 开机自启

pm2 start ecosystem.config.js --env production
pm2 save
pm2 startup

# 务必执行 pm2 startup 输出的那条 sudo 命令

pm2 save

验证：重启服务器后执行 pm2 list，进程应为 online。

取消自启：pm2 unstartup systemd

生产建议：使用独立 deploy 用户运行 PM2，不要用 root。

12. 环境变量与多环境

env: { NODE_ENV: 'development', PORT: 3000 },
env_production: { NODE_ENV: 'production', PORT: 80 },
env_staging: { NODE_ENV: 'staging', PORT: 3001 },

pm2 start ecosystem.config.js --env production
pm2 restart myapp --update-env --env production

PM2 不自动读 .env，可在应用入口用 dotenv，或：

pm2 start app.js --node-args="-r dotenv/config"

13. 部署与更新

cd /var/www/myapp
git pull
npm ci --production
npm run build
pm2 reload myapp
pm2 save

• 集群应用：用 pm2 reload 实现零停机
• 单实例：可用 restart，高可用请改为多实例 + reload

14. 监控与告警

pm2 monit
pm2 show myapp

• 系统资源：htop、df -h
• 日志目录：~/.pm2/logs
• 可选云服务：pm2.io

15. 日常运维清单

每日 / 每周

• pm2 list 确认状态为 online
• pm2 logs --lines 50 抽查错误
• 检查磁盘空间
• 关注 restart 次数是否异常

发版后

• pm2 reload 或 restart
• pm2 save
• 接口健康检查 / 冒烟测试

安全

• 生产环境避免 root 跑 Node
• 防火墙只开放 80 / 443
• 定期 npm audit 与 apt upgrade

16. 故障排查

16.1 EBADENGINE：Node 版本过低

required: { node: '>=18.0.0' }
current:  { node: 'v12.22.9' }

处理：按本文 第 4 节 升级到 Node 18+。

16.2 状态 errored 或反复重启

pm2 logs myapp --err --lines 100
pm2 show myapp
pm2 restart myapp

常见原因：端口占用、环境变量缺失、数据库不可用、代码语法错误。

16.3 端口被占用

sudo lsof -i :3000
sudo ss -tlnp | grep 3000

16.4 PM2 命令找不到

export PATH="$PATH:$(npm config get prefix)/bin"

写入 ~/.bashrc 后 source ~/.bashrc。

16.5 开机未自启

1. 是否执行了 pm2 startup 输出的 sudo 命令
2. 是否执行了 pm2 save
3. systemctl status pm2-root 查看服务状态

16.6 完全重置 PM2

pm2 kill
rm -rf ~/.pm2
pm2 start ecosystem.config.js
pm2 save
pm2 startup

17. 附录：命令速查表

# 安装

sudo npm install pm2 -g

# 启动

pm2 start app.js --name myapp
pm2 start ecosystem.config.js --env production

# 查看

pm2 list
pm2 show myapp
pm2 logs myapp

# 控制

pm2 stop myapp
pm2 restart myapp
pm2 reload myapp
pm2 delete myapp

# 持久化

pm2 save
pm2 startup

# 维护

pm2 flush
pm2 monit

参考链接

• PM2 官方文档
• NodeSource 安装说明
• ecosystem 配置说明

文档版本 1.0 · Ubuntu 22.04 + Node 20 + PM2 7.0.1 实机整理