PM2 使用详解：Node.js 项目后台运行、守护进程、日志与生产部署

一、PM2 是什么

PM2 是一个常用的 Node.js 进程管理工具，主要用于生产环境中管理 Node 服务。

它可以帮我们解决几个很实际的问题：

让 Node.js 应用在后台运行
应用崩溃后自动重启
查看进程状态、CPU、内存占用
管理日志
支持多进程 Cluster 模式
服务器重启后自动恢复服务
通过配置文件统一管理多个应用

简单来说，开发环境可以用 node app.js 或 npm run dev，但生产环境更推荐用 PM2 管理服务。

官方文档：PM2 Documentation

二、安装 PM2

PM2 通常全局安装：

bash 复制代码

npm install pm2 -g

查看版本：

bash 复制代码

pm2 -v

如果能正常输出版本号，说明安装成功。

三、启动一个 Node.js 应用

假设项目入口文件是 app.js：

bash 复制代码

pm2 start app.js

给进程指定名称：

bash 复制代码

pm2 start app.js --name my-api

如果是通过 npm script 启动，例如：

json 复制代码

{
  "scripts": {
    "start": "node dist/main.js"
  }
}

可以这样启动：

bash 复制代码

pm2 start npm --name my-api -- run start

查看当前运行的应用：

bash 复制代码

pm2 list

常见状态包括：

online：运行中
stopped：已停止
errored：启动失败或运行异常

四、常用进程管理命令

停止应用：

bash 复制代码

pm2 stop my-api

重启应用：

bash 复制代码

pm2 restart my-api

重新加载应用：

bash 复制代码

pm2 reload my-api

删除应用：

bash 复制代码

pm2 delete my-api

查看应用详情：

bash 复制代码

pm2 show my-api

或者：

bash 复制代码

pm2 describe my-api

查看实时监控面板：

bash 复制代码

pm2 monit

pm2 monit 可以看到应用的 CPU、内存、重启次数、日志等信息，排查线上问题时很方便。

五、查看日志

查看所有应用日志：

bash 复制代码

pm2 logs

查看指定应用日志：

bash 复制代码

pm2 logs my-api

查看最近 200 行日志：

bash 复制代码

pm2 logs my-api --lines 200

清空日志：

bash 复制代码

pm2 flush

生产环境中建议安装日志切割插件，避免日志文件无限增长：

bash 复制代码

pm2 install pm2-logrotate

PM2 官方也推荐使用 pm2-logrotate 处理日志轮转。

六、使用 ecosystem 配置文件

命令行启动适合简单场景，但生产环境更推荐使用配置文件。

生成配置文件：

bash 复制代码

pm2 ecosystem

或者手动创建 ecosystem.config.js：

js 复制代码

module.exports = {
  apps: [
    {
      name: 'my-api',
      script: 'dist/main.js',
      cwd: '/www/my-api',

      instances: 1,
      exec_mode: 'fork',

      env: {
        NODE_ENV: 'development',
        PORT: 3000
      },

      env_production: {
        NODE_ENV: 'production',
        PORT: 3000
      },

      autorestart: true,
      max_memory_restart: '512M',

      out_file: './logs/out.log',
      error_file: './logs/error.log',
      log_date_format: 'YYYY-MM-DD HH:mm:ss',

      watch: false,
      ignore_watch: ['node_modules', 'logs']
    }
  ]
}

启动生产环境配置：

bash 复制代码

pm2 start ecosystem.config.js --env production

重启并更新环境变量：

bash 复制代码

pm2 restart ecosystem.config.js --env production --update-env

如果修改了 env_production，但发现环境变量没有生效，通常需要加上 --update-env。

七、Cluster 集群模式

PM2 支持 Cluster 模式，可以让 Node.js 应用启动多个进程，充分利用多核 CPU。

命令行方式：

bash 复制代码

pm2 start app.js -i max

max 表示根据 CPU 核心数自动启动实例。

配置文件方式：

js 复制代码

module.exports = {
  apps: [
    {
      name: 'my-api',
      script: 'dist/main.js',
      instances: 'max',
      exec_mode: 'cluster'
    }
  ]
}

启动：

bash 复制代码

pm2 start ecosystem.config.js

扩容到 4 个实例：

bash 复制代码

pm2 scale my-api 4

Cluster 模式适合 HTTP、TCP 这类无状态服务。

如果应用依赖本地内存状态、WebSocket 粘性会话或定时任务，需要额外设计，不能简单粗暴地开多实例。

八、服务器重启后自动恢复

PM2 只负责当前会话里的进程管理。要让服务器重启后自动恢复应用，需要执行：

bash 复制代码

pm2 startup

执行后，PM2 会输出一条带 sudo 的命令，把它复制执行一遍。

然后保存当前进程列表：

bash 复制代码

pm2 save

以后服务器重启时，PM2 会根据保存的进程列表自动恢复应用。

如果后续新增、删除、修改了 PM2 进程，记得重新执行：

bash 复制代码

pm2 save

否则重启服务器后恢复的仍然是旧进程列表。

九、生产环境部署流程示例

一个常见的 Node.js 项目部署流程如下：

bash 复制代码

cd /www/my-api

git pull

npm ci

npm run build

pm2 reload ecosystem.config.js --env production --update-env

pm2 save

如果不是 Cluster 模式，也可以使用：

bash 复制代码

pm2 restart ecosystem.config.js --env production --update-env

一般来说：

restart：直接重启，简单直接
reload：平滑重载，更适合 Cluster 模式
--update-env：更新环境变量
pm2 save：保存当前进程列表，方便服务器重启后恢复

十、常见问题

1. 修改环境变量后不生效

使用：

bash 复制代码

pm2 restart my-api --update-env

或者：

bash 复制代码

pm2 restart ecosystem.config.js --env production --update-env

2. 服务器重启后应用没有自动启动

检查是否执行过：

bash 复制代码

pm2 startup
pm2 save

注意：只执行 pm2 startup 不够，还需要 pm2 save 保存进程列表。

3. 日志文件越来越大

安装日志轮转插件：

bash 复制代码

pm2 install pm2-logrotate

也可以定期清空日志：

bash 复制代码

pm2 flush

4. 项目是 ESM，ecosystem 配置报错

如果项目的 package.json 里配置了：

json 复制代码

{
  "type": "module"
}

建议把 PM2 配置文件命名为：

bash 复制代码

ecosystem.config.cjs

然后使用：

bash 复制代码

pm2 start ecosystem.config.cjs --env production

5. 不建议把 PM2 当成万能部署工具

PM2 很适合传统服务器部署 Node.js 应用。

但如果项目已经运行在 Docker、Kubernetes 这类容器编排环境中，就需要谨慎使用 PM2，避免进程管理职责重复。

十一、常用命令速查

bash 复制代码

pm2 start app.js --name my-api
pm2 start npm --name my-api -- run start

pm2 list
pm2 show my-api
pm2 monit

pm2 stop my-api
pm2 restart my-api
pm2 reload my-api
pm2 delete my-api

pm2 logs my-api
pm2 logs my-api --lines 200
pm2 flush

pm2 start ecosystem.config.js --env production
pm2 restart ecosystem.config.js --env production --update-env

pm2 startup
pm2 save

pm2 scale my-api 4
pm2 install pm2-logrotate

十二、总结

PM2 是 Node.js 项目生产部署中非常实用的进程管理工具。它不仅能让应用后台运行，还能提供自动重启、日志管理、进程监控、Cluster 多进程、开机自启等能力。

如果只是本地开发，直接使用 npm run dev 就可以；但如果是线上服务，建议使用 ecosystem.config.js 管理 PM2 配置，让启动方式、环境变量、日志路径和进程策略都变得清晰可维护。

参考资料：