PM2 使用教程（Node.js 进程守护工具）

PM2 是 Node.js 最常用的进程管理器，可以让你的应用在后台持久运行，支持自动重启、负载均衡、日志管理等功能。

倾听风雨著 2026-07-30
更多教程请去网址：https://blog.qtfyu.top/

===========================================================================
目 录
===========================================================================

1. 安装 PM2
2. 启动应用
3. 常用管理命令
4. 日志管理
5. 开机自启
6. 集群模式
7. 环境变量
8. 常见问题
9. 快速参考卡片
10. 完整部署示例

===========================================================================
1. 安装 PM2
===========================================================================

    # 全局安装
    npm install -g pm2

    # 验证安装
    pm2 --version

===========================================================================
2. 启动应用
===========================================================================

2.1 基础启动
----------------------------------------

    # 启动单个文件
    pm2 start index.mjs

    # 指定应用名称（推荐）
    pm2 start index.mjs --name "my-app"

    # 启动时指定参数
    pm2 start index.mjs --name "my-app" -- --port 3000

2.2 使用配置文件启动（推荐）
----------------------------------------

在项目根目录创建 ecosystem.config.js：

    module.exports = {
      apps: [
        {
          name: 'my-app',              // 应用名称
          script: './index.mjs',       // 启动文件
          cwd: '/opt/my-project',      // 工作目录（可选）
          instances: 1,                // 实例数量（1 或 'max' 使用全部CPU）
          exec_mode: 'fork',           // 执行模式：fork 或 cluster

          // 环境变量
          env: {
            NODE_ENV: 'development',
            PORT: 3000
          },
          env_production: {
            NODE_ENV: 'production',
            PORT: 3000
          },

          // 自动重启
          autorestart: true,

          // 内存限制（超过自动重启）
          max_memory_restart: '500M',

          // 日志配置
          log_file: './logs/combined.log',
          out_file: './logs/out.log',
          error_file: './logs/error.log',
          log_date_format: 'YYYY-MM-DD HH:mm:ss Z',

          // 监听文件变化自动重启（开发环境用）
          watch: false,
          ignore_watch: ['node_modules', 'logs'],

          // 延迟启动
          restart_delay: 3000,

          // 最大重启次数（防止无限重启）
          max_restarts: 10,

          // 最小运行时间
          min_uptime: '10s'
        }
      ]
    };

启动命令：

    pm2 start ecosystem.config.js

    # 指定环境
    pm2 start ecosystem.config.js --env production

===========================================================================
3. 常用管理命令
===========================================================================

    # 查看所有应用状态
    pm2 status

    pm2 ls

    pm2 list

    # 查看某个应用详情
    pm2 show my-app

    pm2 describe my-app

    # 查看应用监控面板（实时）
    pm2 monit

    # 重启应用
    pm2 restart my-app

    pm2 restart all          # 重启所有

    # 停止应用（不删除）
    pm2 stop my-app

    pm2 stop all

    # 删除应用
    pm2 delete my-app

    pm2 delete all

    # 重载应用（0 停机时间，仅 cluster 模式）
    pm2 reload my-app

    # 查看应用日志
    pm2 logs my-app

    pm2 logs my-app --lines 50    # 查看最新50行

    pm2 logs --lines 100           # 查看所有应用最新100行

    pm2 logs my-app --timestamp    # 带时间戳

    # 清空日志（全局操作，不支持按应用）
    pm2 flush

    # 保存当前进程列表（用于开机自启）
    pm2 save

⚠️ 警告：pm2 flush my-app 这种按应用清空日志的写法无效，flush 是全局操作，会清空所有应用的日志。

===========================================================================
4. 日志管理
===========================================================================

    # 实时查看日志
    pm2 logs

    # 查看指定应用日志
    pm2 logs my-app

    # 查看历史日志（带行数限制）
    pm2 logs my-app --lines 200

    # 只查看错误日志
    pm2 logs my-app --err

    # 只查看标准输出
    pm2 logs my-app --out

日志文件默认位置：

    ~/.pm2/logs/          # 全局日志目录
    ./logs/               # 如果在配置中指定了相对路径

===========================================================================
5. 开机自启
===========================================================================

    # 生成开机启动脚本（根据系统类型自动生成）
    pm2 startup

    # 执行输出的命令（需要 root 权限）
    # 例如：sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u username --hp /home/username

    # 保存当前运行的进程列表
    pm2 save

    # 取消开机自启
    pm2 unstartup systemd

重要：pm2 startup 只是生成命令，必须复制并执行它输出的那行命令才能真正生效。

===========================================================================
6. 集群模式（多核利用）
===========================================================================

    # 启动多个实例，利用全部 CPU 核心
    pm2 start index.mjs -i max

    # 或指定实例数
    pm2 start index.mjs -i 4

在 ecosystem.config.js 中配置：

    instances: 'max'
    exec_mode: 'cluster'

===========================================================================
7. 环境变量
===========================================================================

启动时传入环境变量：

    pm2 start index.mjs --name "my-app" --env production

在 ecosystem.config.js 中定义：

    env: {
      NODE_ENV: 'development',
      PORT: 3000,
      DATABASE_URL: 'mysql://localhost:3306/mydb'
    }

提示：环境变量建议在 ecosystem.config.js 中集中管理，不要在命令行里写一堆 --env。

===========================================================================
8. 常见问题
===========================================================================

Q1: pm2 启动后访问不了？
----------------------------------------

    - 检查应用是否监听 0.0.0.0（不能仅监听 127.0.0.1）
    - 检查防火墙是否放行端口
    - 查看日志：pm2 logs my-app

Q2: 修改代码后如何生效？
----------------------------------------

    pm2 restart my-app

开发环境可开启 watch 模式：

    pm2 start index.mjs --watch

Q3: 如何更新 PM2？
----------------------------------------

    npm install -g pm2@latest

    pm2 update

Q4: 服务器重启后应用没了？
----------------------------------------

    pm2 save        # 保存进程列表

    pm2 startup    # 设置开机自启（记得执行输出的命令）

===========================================================================
9. 快速参考卡片
===========================================================================

    pm2 start app.js                    启动应用
    pm2 start app.js --name "xxx"     指定名称启动
    pm2 status / ls / list            查看状态
    pm2 restart xxx                   重启
    pm2 stop xxx                      停止
    pm2 delete xxx                    删除
    pm2 logs xxx                      查看日志
    pm2 monit                         监控面板
    pm2 save                          保存进程列表
    pm2 startup                       设置开机自启
    pm2 flush                         清空日志

===========================================================================
10. 完整部署示例
===========================================================================

    # 1. 进入项目目录
    cd /opt/my-project

    # 2. 安装依赖
    npm install

    # 3. 用 pm2 启动
    pm2 start index.mjs --name "my-app"

    # 4. 保存进程列表
    pm2 save

    # 5. 设置开机自启（复制并执行输出的命令）
    pm2 startup

    # 6. 查看状态确认
    pm2 status

===========================================================================
文档版本：2026-07-30
===========================================================================