PM2 完整详细使用教程

PM2 是 Node.js 生产环境进程管理器，核心能力：进程守护、自动重启、集群负载均衡、日志管理、开机自启、性能监控。

环境：Node.js（fnm/nvm管理多版本），支持 Linux/macOS；Windows 部分功能受限，生产建议 Linux。

一、安装

# 全局安装
npm install pm2 -g

# 查看版本
pm2 -v

⚠️ fnm 环境注意：全局安装的 pm2 绑定当前 node 版本；切换 node 版本后，需要重新 npm i pm2 -g。

二、基础启动命令

1. 直接启动脚本

# 基础启动，自动生成随机名字
pm2 start app.js

# 指定应用名称（后续用名字操作）
pm2 start app.js --name api-server

# 传递 node 参数，-- 后面是给 node 的参数
pm2 start app.js --name api -- --max-old-space-size=1024

# 传递程序参数
pm2 start app.js --name api -- --port 3001 --env prod

2. 启动 npm script

很多项目入口写在 package.json scripts，不能直接 pm2 start npm，格式：

# 对应 npm run start
pm2 start npm --name myapp -- run start

# npm run serve
pm2 start npm --name myapp -- run serve

3. 两种执行模式 fork / cluster

  • fork（默认）：单进程，简单，不做负载均衡；适合小服务、有状态程序。
  • cluster：多实例集群模式，利用多核CPU，端口复用，零停机重载；适合无状态API服务。
# -i / --instances 指定实例数量
pm2 start app.js --name cluster-api -i 2 --exec-mode cluster

# max：自动等于CPU核心数
pm2 start app.js --name cluster-api -i max --exec-mode cluster

cluster 模式限制：程序不能依赖本地 socket、不能维持长连接状态；数据库连接池需要每个实例独立。

4. 进程生命周期命令

pm2 start <name|id|file>     # 启动
pm2 restart <name|id>        # 硬重启：杀死进程，重新拉起，会断连接
pm2 reload <name|id>         # ✅集群模式优雅重载，0停机更新，不切断现有连接
pm2 stop <name|id>           # 停止进程，保留在pm2列表
pm2 delete <name|id>         # 删除进程，从pm2列表移除
pm2 reset <name|id>          # 重置重启计数

查看 id：pm2 list，每一条进程有数字 id，可以用 id 代替名字操作。

三、状态、日志、监控

1. 查看进程列表

pm2 list
pm2 ls
pm2 status

输出字段含义：

  • id：进程ID
  • name：应用名
  • mode：fork / cluster
  • status：online / stopped / errored
  • restart：异常重启次数，数值持续上涨代表程序不断崩溃
  • cpu、mem：资源占用

2. 查看详情

pm2 show api-server

会显示路径、日志路径、启动参数、环境变量、重启历史。

3. 日志

# 实时输出全部日志
pm2 logs

# 指定应用日志
pm2 logs api-server

# 只看错误日志
pm2 logs api-server --err

# 只看标准输出日志
pm2 logs api-server --out

# 输出最近200行历史，不阻塞
pm2 logs api-server --lines 200 --no-daemon

# 清空所有历史日志文件
pm2 flush

pm2 默认日志存放在 ~/.pm2/logs/。

4. 交互式监控面板

pm2 monit

可以查看每个进程CPU、内存、日志输出，上下键切换应用，q退出。

四、配置文件 ecosystem.config.js（生产必用）

不建议大量使用命令行参数；复杂项目统一用配置文件管理。

生成模板

# 生成简单版 ecosystem.config.js
pm2 init simple

完整参考配置 ecosystem.config.js

module.exports = {
  apps: [
    {
      // 应用基础
      name: "api-server",
      script: "./app.js",                // 入口文件
      interpreter: "/home/user/.fnm/node-versions/v22.14.0/installation/bin/node", // fnm环境写绝对node路径，解决开机自启版本不对
      instances: "max",
      exec_mode: "cluster",

      // 环境变量
      env: {
        NODE_ENV: "production",
        PORT: 3000
      },
      env_development: {
        NODE_ENV: "development",
        PORT: 3001
      },

      // 行为控制
      autorestart: true,                // 程序崩溃自动重启
      watch: false,                     // 文件监听，生产关闭，开发改为true
      watch_options: {
        ignored: ["node_modules", "logs"]
      },
      max_memory_restart: "400M",       // 内存超过自动重启，防止内存泄漏

      // 日志配置
      out_file: "./logs/out.log",
      error_file: "./logs/err.log",
      merge_logs: true,                 // cluster多实例日志合并到一个文件
      log_date_format: "YYYY-MM-DD HH:mm:ss",

      // 错误行为
      restart_delay: 3000,              // 崩溃后延迟3秒再重启，防止疯狂重启
      min_uptime: "10s"                 // 运行至少10s才算启动成功
    }
  ]
}

使用配置文件

# 使用production环境
pm2 start ecosystem.config.js --env production

# 使用development环境
pm2 start ecosystem.config.js --env development

pm2 restart ecosystem.config.js
pm2 stop ecosystem.config.js
pm2 delete ecosystem.config.js

.gitignore 建议加入：logs/、ecosystem.config.js（本机路径不同，不要提交，可提交 ecosystem.config.sample.js）

五、开机自启配置（服务器断电重启自动恢复服务）

⚠️ fnm 用户大坑：pm2 startup 创建系统服务，不读取 shell 的 fnm 环境变量。
✅ 解决方案：在 ecosystem.config.js 填写 interpreter node 绝对路径。

# 1.生成系统开机服务脚本（根据系统输出复制执行）
pm2 startup

# 2.保存当前运行的进程快照，开机自动恢复这些应用
pm2 save

相关命令

pm2 save               # 保存当前进程快照 ~/.pm2/dump.pm2
pm2 resurrect          # 手动恢复保存的进程
pm2 cleardump          # 删除保存的快照，开机不再启动
pm2 unstartup          # 移除pm2开机自启服务

测试开机自启：重启服务器，执行 pm2 list，看应用是否自动 online。

六、日志切割 pm2‑logrotate

pm2 默认日志不会自动切割，时间久文件巨大。安装日志轮转模块：

pm2 install pm2-logrotate

查看配置

pm2 conf pm2-logrotate

常用配置项

  • max_size: 100M 文件超过大小分割
  • retain: 30 最多保留30个历史日志文件
  • dateFormat: YYYY-MM-DD_HH-mm-ss

设置示例

pm2 set pm2-logrotate:max_size 100M
pm2 set pm2-logrotate:retain 30

七、开发环境 vs 生产环境最佳实践

🧑‍💻开发环境

  • watch:true，文件修改自动重启
  • 不用 cluster，fork模式即可
  • 不配置 max_memory_restart
  • 直接 pm2 start ecosystem.config.js --env development

🚀生产环境

  1. 关闭 watch:true，避免文件改动意外重启
  2. API服务优先 exec_mode:"cluster"
  3. 设置 max_memory_restart，防护内存泄漏
  4. 设置 restart_delay，防止代码bug造成无限快速重启
  5. 使用 pm2‑logrotate 切割日志
  6. fnm环境必须配置 interpreter node绝对路径，保证开机自启版本正确
  7. 更新代码部署：使用 pm2 reload 实现零停机更新，不要用 restart
  8. 监控 pm2 list 的 restart 字段，持续上涨代表服务异常

部署更新示例流程：

git pull
npm install
pm2 reload ecosystem.config.js --env production

八、常见坑点与排错

  1. pm2启动node版本不是fnm切换的版本

pm2 startup生成的系统服务不读取shell环境变量。配置文件写死 interpreter node二进制绝对路径。

  1. restart 数值疯狂上涨，服务一直重启
pm2 logs <app-name> --err

看报错：端口占用、代码异常、数据库连不上、内存溢出。

  1. cluster模式端口被占用

cluster模式多个实例共享同一个端口，不需要改端口号。

  1. 项目更新后不生效
  • fork模式：pm2 restart
  • cluster模式：pm2 reload
  1. pm2 save 后重启服务器进程没起来
  • 确认 pm2 startup 执行成功
  • 检查 interpreter node路径是否有效
  • 查看系统日志 journalctl -u pm2-root
  1. Windows环境
    Windows下 pm2 startup 功能不完善，生产不建议Windows部署Node服务。

九、常用命令速查表

pm2 start app.js --name xxx         # 启动
pm2 start ecosystem.config.js       # 通过配置文件启动
pm2 list                            # 进程列表
pm2 show xxx                        # 详情
pm2 logs xxx                        # 日志
pm2 monit                           # 监控面板
pm2 restart xxx                     # 硬重启
pm2 reload xxx                      # 集群优雅重载
pm2 stop xxx                        # 停止
pm2 delete xxx                      # 删除进程
pm2 flush                           # 清空日志
pm2 startup                         # 生成开机脚本
pm2 save                            # 保存进程快照
pm2 resurrect                       # 恢复快照
pm2 install pm2-logrotate           # 日志轮转