PM2 备忘清单

NPM version Downloads

PM2 是 Node.js / Bun 应用常用的生产进程管理器，提供守护进程、自动重启、日志、监控、集群模式、开机自启和配置文件管理能力。它也可以启动脚本、Python 程序或二进制文件。

入门

安装与版本

:----
npm install pm2@latest -g使用 npm 全局安装最新版
yarn global add pm2使用 Yarn 全局安装
pm2 -v查看 PM2 版本
pm2 update更新内存中的 PM2 daemon
pm2 ping检查 PM2 daemon 是否可用
pm2 kill停止 PM2 daemon 和所有受管进程

升级全局包后执行 pm2 update，让正在运行的 daemon 使用新版本。

启动应用

:----
pm2 start app.js启动 Node.js 应用
pm2 start app.js --name api指定应用名称
pm2 start app.js --watch文件变化时自动重启
pm2 start app.js --time日志输出添加时间前缀
pm2 start app.js --no-autorestart禁用自动重启
pm2 start app.js --max-memory-restart 300M超过内存阈值后重启
pm2 start script.sh启动 Shell 脚本
pm2 start worker.py --interpreter python3指定解释器启动脚本
pm2 start app.js -- --port 3000-- 后参数传给应用

示例

$ pm2 start app.js --name api --time
$ pm2 start server.js --watch --ignore-watch="node_modules logs"
$ pm2 start app.js -- --port 3000

进程操作

:----
pm2 list | pm2 ls | pm2 status列出受管进程
`pm2 restart <nameid
`pm2 reload <nameid
`pm2 stop <nameid
`pm2 delete <nameid
`pm2 describe <nameid>`
`pm2 reset <nameid

reload 与 restart 不同：reload 会尝试平滑替换进程；若超时或不适用，PM2 会回退到普通重启。

日志与监控

日志

:----
pm2 logs实时查看所有进程日志
pm2 logs api查看指定应用日志
pm2 logs --lines 200输出最近 200 行后继续跟随
pm2 logs --nostream只打印日志，不持续跟随
pm2 logs --json以 JSON 格式输出日志
pm2 logs --err只显示错误输出
pm2 logs --out只显示标准输出
pm2 flush清空所有日志
pm2 flush api清空指定应用日志
pm2 reloadLogs重新打开日志文件，常用于 logrotate 后

日志默认位于 $HOME/.pm2/logs。启动时可用 --log、--output、--error、--time、--log-date-format、--merge-logs 控制日志路径和格式。

监控

:----
pm2 monit打开终端实时监控面板
pm2 show api查看指定应用状态、日志路径、环境等信息
pm2 prettylist以格式化 JSON 输出进程列表
pm2 jlist输出原始 JSON 进程列表
pm2 report生成诊断报告
pm2 plus连接 PM2 Plus / PM2.io 在线监控

集群与扩缩容

Cluster 模式

:----
pm2 start app.js -i max根据可用 CPU 数启动实例
pm2 start app.js -i 0与 max 类似，启动尽可能多实例
pm2 start app.js -i 4启动 4 个实例
pm2 reload api对应用做零停机 reload
pm2 scale api +2增加 2 个实例
pm2 scale api 4调整到总共 4 个实例

Cluster 模式适合监听 HTTP、TCP、UDP 等网络端口的 Node.js 应用。配置文件中需要显式设置 exec_mode: "cluster"，否则默认不会启用负载均衡。

Cluster 配置示例

module.exports = {
  apps: [{
    name: "api",
    script: "./server.js",
    instances: "max",
    exec_mode: "cluster"
  }]
}

配置文件

ecosystem.config.js

:----
pm2 init simple生成基础 ecosystem.config.js
pm2 start ecosystem.config.js启动配置文件中的应用
pm2 restart ecosystem.config.js重启配置文件中的应用
pm2 reload ecosystem.config.jsreload 配置文件中的应用
pm2 stop ecosystem.config.js停止配置文件中的应用
pm2 delete ecosystem.config.js删除配置文件中的应用
pm2 start ecosystem.config.js --only api只操作指定应用
pm2 start ecosystem.config.js --env production使用 env_production

配置文件建议以 .config.js 结尾，便于 PM2 识别。

配置示例

module.exports = {
  apps: [{
    name: "api",
    script: "./server.js",
    instances: 2,
    exec_mode: "cluster",
    watch: false,
    max_memory_restart: "300M",
    env: {
      NODE_ENV: "development",
      PORT: 3000
    },
    env_production: {
      NODE_ENV: "production",
      PORT: 8080
    }
  }, {
    name: "worker",
    script: "./worker.js",
    autorestart: true
  }]
}

环境变量

:----
env默认环境变量
env_production--env production 时注入
env_staging--env staging 时注入
NODE_APP_INSTANCEPM2 为每个实例注入的实例编号
instance_var重命名实例编号变量
increment_var为每个实例递增某个环境变量
--update-env重启时更新环境变量

示例

$ PORT=4000 pm2 restart api --update-env
$ pm2 start ecosystem.config.js --env production

重启策略

常见策略

:----
pm2 start app.js --watch文件变化时自动重启
pm2 stop app --watch停止并禁用 watch 重启
pm2 restart app --watch切换 watch 选项
pm2 start app.js --restart-delay=3000自动重启前等待 3000ms
pm2 start app.js --cron-restart="0 0 * * *"每天 0 点重启
pm2 restart app --cron-restart 0禁用 cron 重启
pm2 start app.js --exp-backoff-restart-delay=100使用指数退避重启
pm2 start app.js --stop-exit-codes 0退出码为 0 时不自动重启

PM2 默认会在应用崩溃、退出或 Node.js 事件循环为空时尝试重启。重启策略可以在 CLI 中设置，也可以写入配置文件。

配置字段

:----
watch: true启用文件监听
ignore_watch: ["node_modules"]忽略监听目录
watch_delay: 1000文件变化后延迟重启
max_memory_restart: "300M"达到内存阈值后重启
restart_delay: 3000重启延迟
cron_restart: "0 0 * * *"cron 定时重启
autorestart: false禁用自动重启
stop_exit_codes: [0]指定退出码不触发重启
exp_backoff_restart_delay: 100指数退避重启初始延迟

持久化与开机自启

启动脚本

:----
pm2 startup生成当前平台的开机启动命令
pm2 startup systemd -u www --hp /home/www指定 systemd 用户和家目录
pm2 save保存当前进程列表，用于重启后恢复
pm2 resurrect手动恢复上次保存的进程列表
pm2 unstartup删除当前开机启动配置
systemctl status pm2-<user>查看 systemd 服务状态
journalctl -u pm2-<user>查看 systemd 启动日志

典型生产流程：

$ pm2 start ecosystem.config.js --env production
$ pm2 save
$ pm2 startup
# 复制并执行 pm2 startup 输出的 sudo 命令

升级 Node.js 后需要重新生成启动脚本，避免开机时仍使用旧 Node.js 路径。

常用流程

部署后平滑更新

$ git pull
$ npm ci
$ npm run build
$ pm2 reload ecosystem.config.js --env production
$ pm2 save

单机快速启动 API

$ pm2 start server.js --name api --time --max-memory-restart 300M
$ pm2 logs api --lines 100

清理不再需要的进程

$ pm2 stop old-api
$ pm2 delete old-api
$ pm2 save

常见排障

:----
重启后进程丢失启动或删除进程后忘记执行 pm2 save
开机自启使用旧 Node.jsNode.js 升级后重新执行 pm2 unstartup 和 pm2 startup
环境变量不更新使用 pm2 restart <app> --update-env
日志文件过大使用 pm2 flush、pm2 reloadLogs，并配置外部 logrotate
watch 停止后仍会重启使用 pm2 stop app --watch 彻底关闭 watch
Cluster 未负载均衡配置文件里确认 exec_mode: "cluster"
reload 变成 restart应用未能及时优雅退出，检查连接关闭与超时

查看异常原因

$ pm2 describe api
$ pm2 logs api --err --lines 200
$ pm2 report

参考资料