🧰 安装与平台差异 >>>

# 基础安装
npm install pm2 -g

# 装完先确认 CLI 可用
pm2 -v
pm2 ping

📋 进程清单与状态 >>>

• pm2 list：查看全部进程
• pm2 status list：别名
• pm2 jlist：以 JSON 输出列表
• pm2 prettylist：结构化查看进程信息
• pm2 describe <app>：查看某个进程完整详情
• pm2 monit：打开实时监控面板

# 先确认进程名、ID、模式与状态
pm2 list
pm2 describe api
pm2 monit

🚀 启动与命名 >>>

• pm2 start app.js --name api：启动并命名
• pm2 start server.js --watch：监听文件变动自动重启
• pm2 start worker.js --time：日志带时间戳
• pm2 start ./dist/main.js --max-memory-restart 512M：超内存自动重启
• pm2 start ./script.sh --interpreter bash：指定解释器
• pm2 start app.js -- --port 3000：向应用透传参数

# 生产环境常见启动方式
pm2 start ./dist/server.js \
  --name api \
  --env production \
  --time \
  --max-memory-restart 512M

🔄 生命周期操作 >>>

• pm2 restart <app>：重启目标进程
• pm2 reload <app>：零停机重载，适合集群模式
• pm2 stop <app>：停止但保留定义
• pm2 delete <app>：删除进程定义
• pm2 restart all：重启全部进程
• pm2 delete all：删除全部进程
• pm2 reset <app>：重置重启次数等元信息

# 发布后无中断重载
pm2 reload api
pm2 describe api

🪵 日志管理 >>>

• pm2 logs：查看全部实时日志
• pm2 logs api --lines 200：查看指定进程最近 200 行
• pm2 logs --err：只看错误日志
• pm2 flush：清空日志
• pm2 reloadLogs：重载日志文件句柄
• pm2 install pm2-logrotate：安装日志轮转模块

# 只盯住一个服务的错误
pm2 logs api --err --lines 100

🧬 集群与扩缩容 >>>

• pm2 start app.js -i max：以 CPU 核数启动集群
• pm2 start app.js -i 4：指定实例数
• pm2 scale api 6：扩容或缩容到指定实例数
• pm2 reload api：集群模式零停机重载
• pm2 show api：查看实例分布和模式

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

🧩 Ecosystem 配置 >>>

• pm2 start ecosystem.config.js：按配置文件启动
• pm2 restart ecosystem.config.js --only api：只重启指定 app
• pm2 reload ecosystem.config.js --only api：只热重载指定 app
• pm2 delete ecosystem.config.js：删除该配置下的进程

module.exports = {
  apps: [
    {
      name: "api",
      script: "./dist/server.js",
      cwd: "/srv/myapp",
      instances: 2,
      exec_mode: "cluster",
      env: {
        NODE_ENV: "development",
        PORT: 3000
      },
      env_production: {
        NODE_ENV: "production",
        PORT: 8080
      }
    }
  ]
};

🌍 环境变量与发布环境 >>>

• --env production env_production：选用
• env：默认环境变量
• env_staging：自定义环境组
• appendEnvToName：把环境名追加到进程名

module.exports = {
  apps: [
    {
      name: "api",
      script: "./dist/server.js",
      appendEnvToName: true,
      env: {
        NODE_ENV: "development"
      },
      env_production: {
        NODE_ENV: "production"
      }
    }
  ]
};

👀 Watch 与自动重启 >>>

• pm2 start app.js --watch：监听文件变化
• --ignore-watch="node_modules logs"：忽略目录
• watch_delay：避免频繁连续重启
• restart_delay：重启之间增加延迟
• max_restarts：限制重启次数

module.exports = {
  apps: [
    {
      name: "api-dev",
      script: "./src/server.js",
      watch: ["src"],
      ignore_watch: ["node_modules", "logs"],
      watch_delay: 500
    }
  ]
};

开机自启动与持久化

• pm2 startup：为 Linux / macOS 生成自启动命令
• pm2 save：保存当前进程清单
• pm2 resurrect：从保存的清单恢复
• pm2 unstartup：移除 Linux / macOS 自启动

# Linux / macOS 常见上线顺序
pm2 startup
pm2 save
pm2 resurrect

Windows 自启动

• 适合个人开发机、轻量常驻服务
• 原理是写注册表启动项，登录后自动拉起 PM2
• pm2 save

npm install pm2-windows-startup -g
pm2-startup install

pm2 start app.js --name my-app
pm2 save

# 验证
pm2 ls

# 卸载
pm2-startup uninstall

• pm2-installer
• pm2-windows-service DEPRECATED
• PM2_HOME

⚡ 高频命令速用 >>>

1. pm2 start

pm2 start app.js --name api -i 4

2. pm2 stop

pm2 stop <name|id|all>

3. pm2 restart

pm2 restart <name|id|all>

4. pm2 reload

pm2 reload <name|all>

5. pm2 delete

pm2 delete <name|id|all>

6. pm2 list / pm2 ls

7. pm2 logs

pm2 logs api --lines 50 --err

8. pm2 describe

pm2 describe <name|id>

9. pm2 monit

pm2 monit

10. pm2 scale

pm2 scale <name> <num>
pm2 scale <name> +3

11. pm2 save

pm2 save

12. pm2 startup

pm2 startup
pm2 unstartup

🗂️ 速查表 >>>

🤝 优雅启动与停止 >>>

• pm2 reload api：对支持优雅退出的服务做平滑重载
• pm2 start app.js --wait-ready：等待应用显式发送 ready
• pm2 start app.js --listen-timeout 8000：放宽启动等待
• pm2 start app.js --kill-timeout 3000：放宽停止等待
• pm2 start app.js --shutdown-with-message：Windows 下用消息而不是 Unix 信号

process.on("SIGINT", async () => {
  await server.close();
  process.exit(0);
});

process.send?.("ready");

🐳 Docker 与 pm2-runtime >>>

• pm2-runtime ecosystem.config.js --env production：在容器中以前台方式运行
• pm2-runtime start app.js -i max：容器内启动 cluster
• kill_timeout：容器停止时留给应用清理的时间

FROM node:22-alpine
WORKDIR /app
COPY . .
RUN corepack enable && pnpm install --prod
CMD ["pm2-runtime", "ecosystem.config.js", "--env", "production"]

🩺 监控与诊断 >>>

• pm2 show <app>：查看 CPU、内存、重启次数
• pm2 env <id>：查看某个进程的环境变量
• pm2 ping：检查 PM2 daemon 是否可用
• pm2 report：生成诊断报告
• pm2 trigger <app> <action>：调用自定义 action

# 排查某个实例频繁重启
pm2 show api
pm2 logs api --err --lines 200
pm2 env 0

🧯 常见排障 >>>

• cwd
• wait_ready
• ignore_watch
• pm2 start ... --no-daemon pm2-runtime

🧾 版本变更 >>>

v7.0.1

• cmd.exe pm2.cmd
• 修复非 Node 解释器在部分 Ubuntu 路径上的误判问题
• pm2 describe max_memory_restart

v7.0.0

• >= 18：要求 Node.js ，不再支持 Node 16
• 新增 Bun runtime 支持，CLI 和内部依赖也做了较大重构
• os.homedir()
• pm2 serve --ftp