墨灵知识库

Appearance

配置文件 ecosystem.config.js 详解 ​

  • 定位：
    • PM2 声明式配置的唯一权威入口。
    • 命令行传参适合演示，生产配置一律进 ecosystem 文件：可版本管理、可复制、可 --env 切换环境。
  • 文件形式：
    • ecosystem.config.js（CommonJS 导出对象）最常见；
    • 也支持 .json、.cjs。
    • 文件里可以做逻辑（循环生成 apps、读取 .env），这是它比 json 更常用的原因。

最小骨架 ​

js
// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'web',           // 应用名
      script: './src/server.js',  // 入口脚本（相对 cwd）
    },
    // 可以继续加第二个、第三个应用…
  ],
};

启动方式：

bash
pm2 start ecosystem.config.js                 # 启动文件里声明的所有 app
pm2 start ecosystem.config.js --only web      # 只启动其中名为 web 的那个
pm2 start ecosystem.config.js --env production # 注入 env_production（见 §4）

--only web 也可用序号（文件内第几个 app，从 0 起）。

常用字段速查表 ​

默认值以官方文档（撰写时最新 7.x）为准（本表为主要常用项；完整清单见文末官方链接）。4.x–7.x 的核心字段基本一致。

字段作用常用默认
name应用名（pm2 ls 显示）脚本 basename
script入口脚本路径（必填）——
cwd工作目录（脚本内相对路径的基准）启动时所在目录
args传给脚本的参数（字符串或数组）无
interpreter解释器路径，如 node、ts-node、babel-nodenode
node_args / interpreter_args传给解释器的参数，如 --max-old-space-size=4096无
exec_modefork 或 clusterfork
instances实例数：0/max=全部 CPU 核、-1=核数-1、数字=固定个数（对 Node 应用设 instances 会自动启用 cluster）1
max_memory_restart内存超过该值自动重启，如 "512M"不限制
env默认注入的环境变量（对象）{}
env_<name>配合 --env <name> 注入的环境无
autorestart进程异常退出后是否自动重启true
max_restarts“不稳定重启”达到该次数后进程转 errored、不再自动拉起16（见 06）
min_uptime一次“稳定运行”的最小时长（可写 "10s"/"1h"）；未达标的快速重启计为不稳定未设时按“重启间隔 <1s”判定（见 06）
restart_delay每次重启前的固定等待0ms
exp_backoff_restart_delay指数退避重启：首间隔=设定值，逐次翻倍，上限 15s；稳定运行 >30s 后重置不设置则不启用（见 06）
cron_restartcron 表达式定时重启无
kill_timeout停止时等待优雅退出的上限，超时 SIGKILL1600ms
listen_timeout等待应用"就绪"的最长时间（配合 wait_ready）3000ms
wait_ready启动/重载时等待应用发 ready 消息false
watchtrue 或路径数组：监听变更自动重启false
ignore_watchwatch 时忽略的路径（node_modules 等）[]
merge_logs多实例（cluster）日志合写同一文件（去掉文件名中的 pid 后缀；combine_logs 是别名）false
time日志行自动加时间戳false
log_date_format自定义日志时间戳格式；与 time 同属“日志加时间前缀”，官方未标废弃，二者取一无
out_file / error_file自定义 stdout/stderr 日志路径（设为 /dev/null 可禁用落盘）~/.pm2/logs/<name>-out-<pid>.log / -error-<pid>.log
log_file设置后 stdout/stderr 合并写入该文件不设置
pid_file自定义 PID 文件路径~/.pm2/pids/<name>-<id>.pid
instance_varcluster 下区分实例的环境变量名NODE_APP_INSTANCE
increment_var若设置，PM2 会为该环境变量自动递增（多实例取不同值）无
namespace命名空间分组（列表过滤/成组操作）无（支持程度随版本，见 §5）
source_map_support崩溃堆栈是否做 source map 转换true
force同名已存在时是否强制覆盖启动false
kill_signal停止时先发该信号让进程优雅退出，超时再 SIGKILLSIGINT（全局可用环境变量 PM2_KILL_SIGNAL 改）

⚠️ 表内"默认值"一列为常见实现值，实施前请以官方文档与 pm2 describe 实际输出为准；与事实表不一致处本文会在附录勘误。

完整示例（一段顶十段） ​

js
// ecosystem.config.js
const { parsed } = require('dotenv').config(); // 可选：把项目 .env 读进来

module.exports = {
  apps: [
    // ── API 服务：cluster 模式，吃满 CPU ──
    {
      name: 'api',
      script: './dist/server.js',
      exec_mode: 'cluster',
      instances: 'max',               // = CPU 核数
      max_memory_restart: '512M',
      kill_timeout: 5000,             // 优雅退出宽限 5s
      listen_timeout: 8000,
      wait_ready: true,               // 应用就绪后 send('ready')
      time: true,                     // 日志带时间戳
      error_file: '/var/log/app/api-error.log',
      out_file: '/var/log/app/api-out.log',
      merge_logs: true,
      env: {
        NODE_ENV: 'development',
        PORT: 3000,
        ...parsed,                    // 合入 .env 内容
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 8080,
      },
    },

    // ── 定时任务 worker：单实例、自动重启要克制 ──
    {
      name: 'cron-worker',
      script: './jobs/worker.js',
      exec_mode: 'fork',
      instances: 1,
      autorestart: true,
      restart_delay: 3000,            // 崩了等 3s 再拉
      max_restarts: 5,
      exp_backoff_restart_delay: 100,
      cron_restart: '0 3 * * *',      // 每天 3 点整点重启（可选，防内存涨）
    },
  ],
};

对应的启停：

bash
pm2 start ecosystem.config.js --env production
pm2 reload ecosystem.config.js --env production   # 发版用 reload（cluster 零停机）
pm2 stop ecosystem.config.js
pm2 delete ecosystem.config.js
pm2 start ecosystem.config.js --only api

环境变量管理（高频考点） ​

原则：环境变量属于"进程启动参数"，写死在启动那一刻，而不是随时可变的 shell 变量。

三种注入方式 ​

js
env: { NODE_ENV: 'development', DEBUG: '*' },   // ① 默认 env，任何启动都会带上
env_production: { NODE_ENV: 'production' },     // ② 只在 --env production 时合并
bash
# ③ 命令行临时覆盖（不推荐在生产用，容易"人肉失忆"）
FOO=bar pm2 start app.js

--env 的语义 ​

  • pm2 start ecosystem.config.js：注入 env；
  • pm2 start ecosystem.config.js --env production：注入 env 并覆盖/追加 env_production 中的键；
  • 同一键在 env 与 env_production 都有时，env_xxx 优先。

从 .env 读取（推荐做法） ​

PM2 本身不解析 .env，在配置文件中用 dotenv 读出后展开即可：

js
// ecosystem.config.js
require('dotenv').config();   // 读取项目根 .env 到 process.env
module.exports = {
  apps: [{
    name: 'api',
    script: 'app.js',
    env: { ...process.env },  // 一次性展开
  }],
};

注意：pm2 restart 不会刷新环境变量——env 是启动时固化的。改了配置请 pm2 delete + pm2 start（或 pm2 restart --update-env 用 shell 环境覆盖）。

不要在生产用 --update-env 当常规手段 ​

--update-env 会把当前 shell 的全部环境灌给进程，容易把机器上无关变量带进去、掩盖"变量从哪来"的问题。生产应坚持：环境只来自 ecosystem 文件（+ .env）。

多应用 / 批量管理 ​

一个配置文件可以管理多个 app，彼此共享同一份启动逻辑：

bash
pm2 start ecosystem.config.js            # 全部启动
pm2 restart ecosystem.config.js          # 全部重启
pm2 reload ecosystem.config.js --env production
pm2 delete ecosystem.config.js           # 全部删除

pm2 ls --namespace prod                  # 只列出 prod 命名空间的进程

namespace 用于把进程分成若干逻辑组：pm2 ls --namespace <ns> 过滤、pm2 restart <ns> 等成组操作；ecosystem 配置项与 CLI 的支持程度以本机版本帮助为准。

命令行旗标 ↔ 字段对照（记不住就回来查） ​

想实现CLIecosystem 字段
多核多进程-i maxexec_mode:'cluster', instances:'max'
代码改了自动重启--watchwatch:true + ignore_watch
内存超限重启--max-memory-restart 512Mmax_memory_restart:'512M'
定时重启--cron-restart "0 3 * * *"cron_restart:'0 3 * * *'
日志带时间--timetime:true
多实例日志合并--merge-logsmerge_logs:true
优雅停--kill-timeout 5000kill_timeout:5000
等就绪再算活--wait-readywait_ready:true + 应用发 ready
自定义日志路径——out_file / error_file
生产环境变量--env productionenv + env_production

常见误区 ​

  1. 改完 ecosystem 不生效：配置文件只在 start/startOrRestart/reload ecosystem.config.js 时被读取；改了文件要用这些命令重新加载，pm2 restart <name> 读的是 daemon 里已固化的参数。
  2. 把 instances 当数量上限：它是"这次启动几个"，不是"最多几个"。
  3. env 写在 apps 外：环境必须在每个 app 对象内（或在 apps 数组外用变量共享再展开）。
  4. 日志路径指向不存在目录：out_file/error_file 的上级目录需先创建，PM2 不会帮你 mkdir。
  5. watch 开着上生产：watch 默认 false；生产开了会在发布拷贝文件时反复重启，务必 watch:false。

参考链接 ​