pm2 7.0.4 配置参数详解

目标：以 ecosystem.config.js 为核心，逐项讲清 pm2 7.0.4 应用配置参数的含义、默认值与实测效果，覆盖应用身份、执行模式、守护重启策略、日志落盘、多环境变量组与文件监听六类参数，并给出可直接落地的生产配置模板。全部示例均在 Ubuntu 22.04（pm2 7.0.4 / Node.js v22.23.3）实测通过；pm2 安装见《Ubuntu 22.04 安装 pm2 7.0.4 指南》，命令行操作见《pm2 7.0.4 常用 CLI 命令与工具详解》。

一、环境信息

• 操作系统：Ubuntu 22.04（amd64），root 用户操作
• pm2：7.0.4（pm2 --version 实测输出 7.0.4）
• Node.js：v22.23.3；npm：10.9.9
• 应用目录与示例应用：/opt/demoapp/app.js（Node.js 内置 http 模块最小服务，监听 PORT 环境变量指定端口，默认 3000）

const http = require("http");

const port = process.env.PORT || 3000;

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
  res.end("Hello from pm2 demo app, PID=" + process.pid + "\n");
});

server.listen(port, () => {
  console.log("demo app listening on port " + port + ", PID=" + process.pid);
});

• 日志目录（本文示例定制）：/var/log/demoapp/
• pm2 数据目录：/root/.pm2

二、前置条件

• pm2 7.0.4 已安装并验证（pm2 --version → 7.0.4）；
• 已准备第一节示例应用 /opt/demoapp/app.js；
• 已创建日志目录（本文日志参数实测依赖）：

mkdir -p /var/log/demoapp

实测回显（目录已存在时静默，ls -la 确认）：

ls -ld /var/log/demoapp

实测回显：

drwxr-xr-x 2 root root 4096 Oct 18 10:20 /var/log/demoapp

三、参数查看与修改方式

pm2 的配置有三个入口：命令行参数（pm2 start app.js --max-memory-restart 60M，见《pm2 7.0.4 常用 CLI 命令与工具详解》第七章速查表）、ecosystem 配置文件（本文主线，参数集中声明、可版本化、支持多环境）、pm2 set 全局键值（pm2 set <key> <value>，主要面向 pm2 自身行为与模块配置）。三者优先级上，命令行参数与 ecosystem 等价（start 时以「最后一次声明」为准），生产环境推荐 ecosystem 集中管理。

3.1 生成配置文件骨架

pm2 自带模板生成命令：

cd /tmp
pm2 ecosystem

实测回显：

File /tmp/ecosystem.config.js generated

生成的默认模板（cat ecosystem.config.js 实测照抄）：

module.exports = {
  apps : [{
    script: 'index.js',
    watch: '.'
  }, {
    script: './service-worker/',
    watch: ['./service-worker']
  }],

  deploy : {
    production : {
      user : 'SSH_USERNAME',
      host : 'SSH_HOSTMACHINE',
      ref  : 'origin/master',
      repo : 'GIT_REPOSITORY',
      path : 'DESTINATION_PATH',
      'pre-deploy-local': '',
      'post-deploy' : 'npm install && pm2 reload ecosystem.config.js --env production',
      'pre-setup': ''
    }
  }
};

结构解读：顶层 apps 数组每项对应一个受托管应用（可同时声明多个），deploy 段是可选的远程部署配置（配合 pm2 deploy 使用，本文不展开）；日常使用通常以 apps 单应用形态为主。

3.2 核对参数是否生效

配置改完怎么确认真的生效？三个权威核对点（命令实测见《pm2 7.0.4 常用 CLI 命令与工具详解》）：

1. pm2 describe <应用名>：进程身份、执行模式、日志路径一览（实测输出含 exec mode/out log path 等行）；
2. pm2 env <pm_id>：应用进程最终生效的环境变量（多环境排查首选，实测 NODE_ENV: production、PORT: 3001）；
3. pm2 jlist：JSON 形式的完整生效配置（pm2_env 字段即配置快照），脚本化核对的最终裁判。

💡 说明：本文每个参数小节的「实测验证」均以上述命令的回显为依据，读者复现时用同款命令自查即可。

四、参数总览

按功能域归类的主要参数（默认值一列以 pm2 7.0.4 实测与官方文档 Application Declaration 为准）：

关键差异解读：exec_mode 与 instances 决定并发形态（网络服务选 cluster），max_memory_restart 与 autorestart 组成自愈双保险，env/env_production 决定环境注入。下文逐类展开并配实测。

五、核心参数分类详解

本章用一份完整实测配置贯穿讲解。配置文件 /opt/demoapp/ecosystem.config.js 全文如下（实测有效）：

module.exports = {
  apps: [
    {
      name: "demo-eco",
      script: "/opt/demoapp/app.js",
      exec_mode: "cluster",
      instances: 2,
      max_memory_restart: "300M",
      autorestart: true,
      out_file: "/var/log/demoapp/out.log",
      error_file: "/var/log/demoapp/error.log",
      merge_logs: true,
      env: {
        PORT: 3000,
        NODE_ENV: "development"
      },
      env_production: {
        PORT: 3001,
        NODE_ENV: "production"
      }
    }
  ]
};

5.1 应用身份与入口：name / script / cwd

name 指定进程列表应用名（默认取脚本文件名）；script 是入口脚本（绝对路径最稳，实测用 /opt/demoapp/app.js）；cwd 指定应用工作目录（相对路径脚本与相对日志的解析基准）。启动实测：

cd /opt/demoapp
pm2 start ecosystem.config.js

实测回显：

[PM2][WARN] Applications demo-eco not running, starting...
[PM2] App [demo-eco] launched (2 instances)

pm2 list 确认名字与模式生效（实测节选）：

│ 0  │ demo-eco    │ default     │ N/A     │ cluster │ 3878     │ 0s     │ 0    │ online    │ 0%       │ 58.1mb   │ root     │ disabled │
│ 1  │ demo-eco    │ default     │ N/A     │ cluster │ 3885     │ 0s     │ 0    │ online    │ 0%       │ 45.4mb   │ root     │ disabled │

应用名 demo-eco、模式 cluster、2 实例均与配置一致。

5.2 执行模式与实例：exec_mode / instances

exec_mode: "cluster" 启用 Node.js cluster 模式：端口由主进程统一绑定、内置负载均衡分发、支持 reload 零停机；instances: 2 即 2 个 worker（"max" 或 -1 表示按 CPU 核数，instances: -1 比核数少 1）。验证负载均衡（连续请求 4 次）：

curl -s http://localhost:3000/
curl -s http://localhost:3000/
curl -s http://localhost:3000/
curl -s http://localhost:3000/

实测回显（两个实例 PID 轮换）：

Hello from pm2 demo app, PID=3878
Hello from pm2 demo app, PID=3885
Hello from pm2 demo app, PID=3878
Hello from pm2 demo app, PID=3885

💡 技术拓展：exec_mode 取值不止 cluster 一种形态选择——

取值	原理	适用
fork（默认）	单进程直接执行脚本	worker 脚本、非 HTTP 服务
cluster	Node cluster 多 worker 共享端口	HTTP/HTTPS/WebSocket 服务

本文 HTTP 示例采用 cluster，理由：需多核利用与 reload 零停机；fork 模式下 instances 无多实例语义。

5.3 守护与重启策略：autorestart / max_memory_restart / max_restarts / restart_delay

autorestart（默认 true）：进程退出即自动拉起。用崩溃脚本实测（2 秒后 process.exit(1)）：

console.log("crasher started, PID=" + process.pid);
setTimeout(() => { console.error("FATAL: simulated crash!"); process.exit(1); }, 2000);

pm2 start crasher.js --name crasher

5 秒后实测 pm2 list（节选）与错误日志：

│ 3  │ crasher     │ default     │ N/A     │ fork    │ 4143     │ 1s     │ 2    │ online    │ 0%       │ 59.0mb   │ root     │ disabled │

FATAL: simulated crash!
FATAL: simulated crash!

崩溃 2 次被自动拉起 2 次（↺=2），错误日志完整留存——自愈行为直接可观测。设为 false 时（如一次性任务）进程退出后保持 stopped 不再拉起。

max_memory_restart：内存超限自动重启。实测：编写内存泄漏脚本（每 200ms 追加 1MB Buffer 的 leaker.js），以 60M 阈值启动：

pm2 start leaker.js --name leaker --max-memory-restart 60M --time

实测回显（启动后 6 秒，内存增长至 89.3mb）：

│ 2  │ leaker      │ default     │ N/A     │ fork    │ 4017     │ 6s     │ 0    │ online    │ 0%       │ 89.3mb   │ root     │ disabled │

约 14 秒后触发超限重启：实测 pm2 list 显示 leaker ↺=1、PID 从 4017 变 4048；应用日志（--time 时间戳生效）：

2|leaker   | 2026-10-18T10:21:27: leaker listening on port 3002, PID=4017
2|leaker   | 2026-10-18T10:21:48: leaker listening on port 3002, PID=4048

守护进程日志中的事件记录（grep -iE "exceed|memory" /root/.pm2/pm2.log 实测）：

2026-10-18T10:21:48: PM2 log: [PM2][WORKER] Process 2 restarted because it exceeds --max-memory-restart value (current_memory=166830080 max_memory_limit=62914560 [octets])

current_memory=166830080（约 159MB，含缓冲峰值）超过 max_memory_limit=62914560（60M）即触发——排查「应用为什么自己重启了」时先查这行日志。

max_restarts / min_uptime / restart_delay：三者共同构成「崩溃风暴」防线——min_uptime 内退出视为不稳定启动，连续 max_restarts 次（默认 16）不稳定重启后 pm2 停止重试并标记 errored；restart_delay 在每次重启前插入固定延迟；exp_backoff_restart_delay 则按指数增长延迟（如 100ms 起步逐次翻倍），适合依赖外部服务未就绪的应用。参数组合建议：常驻服务保留默认 autorestart + 显式 max_memory_restart；外部依赖未就绪类应用加 exp_backoff_restart_delay: 100。

5.4 日志参数：out_file / error_file / merge_logs / time

示例配置把日志定向到 /var/log/demoapp/ 并开启合并。启动后实测日志落位：

ls -la /var/log/demoapp/
cat /var/log/demoapp/out.log

实测回显：

total 16
drwxr-xr-x 2 root root 4096 Oct 18 10:20 .
drwxr-xr-x 1 root root 4096 Oct 18 10:20 ..
-rw-r--r-- 1 root root    0 Oct 18 10:20 error.log
-rw-r--r-- 1 root root   84 Oct 18 10:20 out.log
demo app listening on port 3000, PID=3878
demo app listening on port 3000, PID=3885

两点验证结论：其一，日志确实写到了自定义目录而非默认 ~/.pm2/logs/；其二，merge_logs 生效时 2 个实例的输出合并在同一个 out.log 中（文件名不带实例编号）。作为对照，不开启 merge_logs 时 cluster 实例日志按实例分文件（实测 pm2 show 中的路径形如 /root/.pm2/logs/web-out-0.log）。time: true（或 CLI --time）给每行日志加时间戳（实测格式 2026-10-18T10:21:27:）；log_date_format 可自定义时间戳格式；日志无限增长靠 pm2 flush 应急清理与 pm2 logrotate 安装按天轮转治理。

5.5 环境变量组：env / env_production / --env

ecosystem 中可声明多组环境变量：env 为默认组，env_<名称> 组由 pm2 start ecosystem.config.js --env <名称> 激活。实测两步验证。

第一步，默认环境启动（上文 5.1 的 pm2 start ecosystem.config.js），验证变量注入与端口：

pm2 env 0 | grep -E "^(NODE_ENV|PORT):"
curl -s http://localhost:3000/
curl -s -m 2 http://localhost:3001/ || echo "(3001 未监听——默认 env 生效)"

实测回显：

NODE_ENV: development
PORT: 3000
Hello from pm2 demo app, PID=3878
(3001 未监听——默认 env 生效)

第二步，切到 production 组（注意需在配置文件所在目录执行，实测在别处执行会报 [PM2][ERROR] File ecosystem.config.js not found）：

pm2 restart ecosystem.config.js --env production

实测回显（输出节选）：

[PM2] Applying action restartProcessId on app [demo-eco](ids: [ 0, 1 ])
[PM2] [demo-eco](0) ✓
[PM2] [demo-eco](1) ✓

验证切换效果：

pm2 env 0 | grep -E "^(NODE_ENV|PORT):"
curl -s http://localhost:3001/
curl -s -m 2 http://localhost:3000/ || echo "(3000 已停止监听——production env 生效)"

实测回显：

NODE_ENV: production
PORT: 3001
Hello from pm2 demo app, PID=3963
(3000 已停止监听——production env 生效)

结论：--env production 后 env_production 组覆盖注入，NODE_ENV 与 PORT 同时切换。可按同样方式扩展 env_staging、env_test 等任意多组。

5.6 文件监听：watch / ignore_watch

watch: true（或 CLI --watch）监听应用目录，文件变更自动重启（开发期热更新用）。实测：

pm2 start app.js --name watcher --watch
touch app.js

实测回显（touch 前后各一次 pm2 list | grep watcher）：

│ 4  │ watcher     │ default     │ N/A     │ fork    │ 8439     │ 1s     │ 0    │ online    │ 0%       │ 59.3mb   │ root     │ enabled  │
│ 4  │ watcher     │ default     │ N/A     │ fork    │ 8476     │ 2s     │ 1    │ online    │ 0%       │ 59.3mb   │ root     │ enabled  │

touch 后 PID 从 8439 变 8476、↺=1，且进程表 watching 列变为 enabled。ignore_watch: ["node_modules", "logs"] 排除无需监听的目录，watch_delay（毫秒）可延迟触发避免编辑器多次保存引发连环重启。生产环境不建议开启 watch：文件监听常驻消耗资源，且配置文件/日志抖动会引发计划外重启，发布的标准动作是 pm2 reload。

5.7 定时与进程控制：cron_restart / kill_timeout / listen_timeout

cron_restart: "0 4 * * *" 每天凌晨 4 点定时重启（需配合 autorestart），适合内存碎片整理类例行重启；kill_timeout: 3000 把停止时等待进程优雅退出的时长从默认 1600ms 延长到 3 秒（给在途请求收尾时间）；listen_timeout 约定 reload 时新实例监听就绪的等待上限。三项均为 millisecond/ cron 标准语义，未单独实测的部分以官方文档 Application Declaration 为准（https://pm2.keymetrics.io/docs/usage/application-declaration/）。

5.8 其他常用项：namespace / uid / gid / interpreter

namespace 把应用划入命名空间便于按域过滤（pm2 list 的 namespace 列，默认 default）；uid/gid 让应用降权运行（如 uid: "www-data"，生产安全基线之一，pm2 以 root 启动时应用进程可切换属主）；interpreter 指定解释器（默认 node，跑 Python 脚本可设 interpreter: "python3"）。以上参数在 pm2 jlist 的 pm2_env 快照中均有对应字段可核对。

六、生产配置模板

适用场景：16GB 内存、NVMe SSD、单机 Node.js Web 服务（4 核 8 线程 CPU），承载 HTTP API 与少量常驻 worker。模板可直接落地：

// /opt/myapp/ecosystem.config.js —— 16GB 内存 / NVMe SSD / Node.js Web 服务单机模板
module.exports = {
  apps: [
    {
      // Web 服务：cluster 模式吃满核，日志集中，生产变量组
      name: "myapp-web",
      script: "./dist/server.js",
      cwd: "/opt/myapp",
      exec_mode: "cluster",
      instances: "max",
      max_memory_restart: "1G",
      autorestart: true,
      exp_backoff_restart_delay: 100,
      out_file: "/var/log/myapp/web-out.log",
      error_file: "/var/log/myapp/web-error.log",
      merge_logs: true,
      time: true,
      kill_timeout: 3000,
      env: {
        NODE_ENV: "development",
        PORT: 3000
      },
      env_production: {
        NODE_ENV: "production",
        PORT: 3000
      }
    },
    {
      // 常驻 worker：fork 单进程，独立日志
      name: "myapp-worker",
      script: "./dist/worker.js",
      cwd: "/opt/myapp",
      exec_mode: "fork",
      instances: 1,
      max_memory_restart: "512M",
      autorestart: true,
      out_file: "/var/log/myapp/worker-out.log",
      error_file: "/var/log/myapp/worker-error.log",
      time: true,
      env_production: {
        NODE_ENV: "production"
      }
    }
  ]
};

逐项说明：

• instances: "max"：Web 服务按 CPU 核数铺满 worker（4 核 8 线程即 8 实例），单 worker 控制在 1G 内存阈值内，总预算约 8G，为系统与缓存留足余量；
• exp_backoff_restart_delay: 100：外部依赖（数据库/缓存）未就绪时指数退避，避免启动期重启风暴；
• kill_timeout: 3000：发布 reload 时给在途请求 3 秒优雅退出窗口；
• merge_logs: true + time: true：多 worker 日志合并单文件并带时间戳，配合 pm2 logrotate 按天轮转；
• worker 应用 fork 单实例：队列消费类任务多实例会引入重复消费，需应用层幂等才可扩多实例；
• 启动与固化：pm2 start ecosystem.config.js --env production && pm2 save，开机自启配合见《Ubuntu 22.04 安装 pm2 7.0.4 指南》第七章。

七、常见问题（FAQ）

Q1：pm2 restart ecosystem.config.js --env production 报 File not found？ 现象：[PM2][ERROR] File ecosystem.config.js not found（实测复现）。定位：pm2 按当前工作目录解析相对路径的配置文件。解决：先 cd 到配置文件目录再执行，或直接用绝对路径 pm2 restart /opt/demoapp/ecosystem.config.js --env production。

Q2：--env production 切换后环境变量没变？ 定位两步：确认执行了 --env production（而不是裸 restart）——裸 restart 沿用启动时快照，实测回显首行会提示 Use --update-env to update environment variables；再用 pm2 env <pm_id> 核对最终生效值（实测 NODE_ENV: production、PORT: 3001）。仍不生效时检查 ecosystem 中变量组名拼写（env_production 对应 --env production）。

Q3：应用频繁自动重启，怎么定位是谁触发的？ 三类重启的判别方法（均有专属日志证据）：崩溃自启看应用错误日志（实测样例 FATAL: simulated crash!）；内存超限重启看守护进程日志（实测样例 [PM2][WORKER] Process 2 restarted because it exceeds --max-memory-restart value (current_memory=166830080 max_memory_limit=62914560 [octets])，位于 /root/.pm2/pm2.log）；watch 触发看进程表 watching 列是否 enabled（实测 touch 文件后 PID 变更、↺ 递增）。pm2 describe <应用名> 的 unstable restarts 计数持续增长说明应用反复异常退出，优先查错误日志。

Q4：merge_logs 开了为什么日志还是分文件？ 定位：merge_logs 只在配置声明的应用上生效；若是 CLI 裸启动（pm2 start app.js -i 2）未带 --merge-logs，日志仍按实例分文件（实测默认路径形如 /root/.pm2/logs/web-out-0.log）。解决：统一改走 ecosystem 配置（本文 5.4 节实测生效），已有应用需 delete 后以配置重启。

八、参考链接

• 官方文档 Application Declaration（ecosystem 全参数）：https://pm2.keymetrics.io/docs/usage/application-declaration/
• 官方文档 cluster 模式：https://pm2.keymetrics.io/docs/usage/cluster-mode/
• 官方文档 日志管理：https://pm2.keymetrics.io/docs/usage/log-management/
• GitHub 仓库：https://github.com/Unitech/pm2
• 本系列配套文档：《pm2 7.0.4 介绍与选型指南》《Ubuntu 22.04 安装 pm2 7.0.4 指南》《pm2 7.0.4 常用 CLI 命令与工具详解》