pm2配置文件并没有想象中复杂，它就是一份名为 ecosystem.config.js 的JavaScript模块，用代码的方式把“项目怎么启动、怎么跑、日志放哪、环境变量是啥”一次性说清楚。相比在命令行里敲一串参数，把配置固定成文件，是2026年Node.js项目部署的工程化基本功，下文会把pm2配置文件的写法、常见字段、生产环境排错和实际场景一次讲透。
为什么需要pm2配置文件
第一次用pm2的人通常会这样启动项目：pm2 start app.js --name myapp，单看这条命令，似乎没什么问题，但项目稍微复杂一点，团队里其他人接手时，会发现几个尴尬的地方。
命令行参数不透明。 新同事想在本地复现生产环境的启动方式，得翻聊天记录或者部署文档，里面可能写着“端口4000，内存限制1G，日志路径自己找”，配置文件把这些信息固定在仓库里，谁拉下来都能直接跑。
多环境部署难处理。 开发环境、测试环境、生产环境，变量不同，启动参数也有差异，用命令行逐个传参，容易漏配置，还容易把测试环境的变量带到生产环境，pm2配置文件天然支持环境变量分组，一套文件搞定三个环境。
进程数量不可控。 写死 -i 4 的写法，在4核服务器上没问题，换成2核服务器就浪费资源，配置里用 instances: 'max' 让进程数跟着CPU核心数走，适配性更强。
日志管理能力缺失。 默认情况下，pm2的日志输出到 ~/.pm2/logs 目录，文件按进程名生成，容易被系统日志清理任务误删，配置文件能显式指定日志路径、按大小切割，和日志采集系统对接也更顺畅。
行业共识认为：部署配置代码化是项目可维护性的分水岭，命令行适合临时调试，配置文件适合长期运行。
pm2配置文件到底怎么写
先看一份最小可用的 ecosystem.config.js，框架如下：
module.exports = {
apps: [
{
name: 'my-app',
script: './src/index.js',
instances: 'max',
exec_mode: 'cluster',
max_memory_restart: '1G',
env: {
NODE_ENV: 'development'
},
env_production: {
NODE_ENV: 'production',
PORT: 8080
},
log_file: './logs/app.log',
out_file: './logs/out.log',
error_file: './logs/error.log',
merge_logs: true,
log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
time: true
}
]
}
这份配置涵盖了最常见的使用需求,逐个拆解关键字段的含义。
name 与 script
name 是显示在pm2面板里的进程名，建议用短横线命名的字符串，my-app。script 是入口文件路径，要用相对配置文件位置的相对路径，或者绝对路径。
这两个字段是基础,也是团队协作时的关键线索，进程名能一眼看出是哪个服务，入口路径能快速定位代码位置。
exec_mode 与 instances
exec_mode 支持 fork 和 cluster。fork 是单进程模式，适合普通的Node.js应用；cluster 是多进程模式，利用多核CPU并行处理请求。
instances 在 cluster 模式下才有意义，设置成 'max' 表示开启和CPU核心数相同的进程数，生产环境建议使用 'max'，避免硬编码数字。
max_memory_restart
这个参数指定进程占用内存的最大值,超过后pm2会自动重启进程，Node.js应用最常见的问题是内存泄漏，这个字段相当于一个保险丝。
一般建议设置为 '1G' 或 '512M'，具体数值根据应用类型调整，如果应用需要缓存大量数据，适当调高。
env 与 env_production
env 是默认环境变量。env_production 是启动时指定 --env production 后生效的变量，可以覆盖 env 里的同名变量。
一个常见的误区是以为 env_production 会自动生效，用 pm2 start ecosystem.config.js 启动时，如果没有额外的 --env 参数，用的就是 env 的内容，务必记住命令：
pm2 start ecosystem.config.js --env production
log_file / out_file / error_file
这三个字段分别指定日志文件路径、标准输出日志路径、错误输出日志路径。log_file 是 out_file 和 error_file 的合并文件，若已指定 out_file 和 error_file，则可以不写 log_file。
merge_logs 表示多进程实例的日志是否合并到同一个文件，建议设为 true，避免每个实例生成一个独立日志文件。
log_date_format 给日志行加上时间戳，格式用 YYYY-MM-DD HH:mm:ss Z 常见。
文件名必须是 ecosystem.config.js 吗
不是,pm2配置文件可以叫任意名字，只是 ecosystem.config.js 是默认约定，用 pm2 start ecosystem.config.js 时pm2会自动查找该文件，自定义文件名时用 pm2 start my.config.js 显式指定。
pm2配置文件在生产环境中的设置要点
配置文件写完后,重点看这几个生产环境相关的功能：负载均衡、自动重启、日志轮转、系统开机启动。
负载均衡与零停机部署
cluster 模式下，pm2会自动把请求分发到不同进程，但这里有个前提：应用内部不能有状态冲突，比如多个进程共享内存变量，会出现数据不同步，如果应用用了Session、Socket.io这类有状态的模块，需要额外配置Redis或其他外部存储，让所有进程共享状态。
生产环境部署新版本时,用滚动重启减少服务中断：
pm2 reload ecosystem.config.js --env production
reload 是逐个重启进程，保证至少有一个进程在服务，如果只是改了环境变量或实例数量，不需要重启整个进程组。
自动重启与守护
应用崩溃后,pm2会自动拉起进程，查看当前的状态和重启次数：
pm2 status
配置文件里已经设了 max_memory_restart，进程内存超标也会自动重启，但要注意，自动重启是兜底策略，不是修复手段，如果应用频繁崩溃，说明代码有问题，要排查原因而不是依赖持续重启。
日志切割与保留
pm2自带的日志功能不切割文件,时间久了日志文件会非常大，需要借助 pm2-logrotate 模块：
pm2 install pm2-logrotate
安装后默认配置是每天切割一次,保留30份，可以在配置里覆盖，也可通过命令调整：pm2 set pm2-logrotate:max_size 100M 表示日志文件超过100MB就切割。
开机自启与systemd
服务器重启后,pm2不会自动启动项目，需要先保存当前进程列表，再生成开机启动脚本：
pm2 save pm2 startup
pm2 startup 命令会输出一条需要复制执行的命令，复制后执行即可，这条命令的本质是创建一个systemd服务，想完全融入系统体系，也可以直接使用systemd服务管理Node.js应用，与pm2的daemon机制实现类似功能，不过pm2的进程守护和自愈能力更完善，多数场景下使用pm2即可。
pm2配置文件的排错实战
这里列举几个写配置时容易踩的坑。
环境变量不生效
检查启动命令有没有带 --env production，如果漏了，使用的就是 env 基础变量，另外注意，env_production 里的变量会覆盖 env 里相同名称的变量。
确认当前生效的环境变量,执行：
pm2 env <app-id>
输出结果里能看到进程启动时注入的所有环境变量。
日志文件一直为空
先确认 out_file 和 error_file 的路径是否存在，且当前用户有写权限，如果路径不存在，pm2不会自动创建目录，需要预先创建。
检查配置文件里是否同时写了 log_file 和 out_file，如果都写了，日志可能写到了 log_file 里，避免同时配置多个日志路径，建议只用 out_file + error_file 组合。
进程一直启不来，状态显示 errored
用 pm2 logs <app-name> 查看错误日志，大部分情况下是入口文件路径错误或端口冲突，个别情况下是 max_memory_restart 设置得太小，进程启动就触发重启。
将内存限制调大,或者暂时注释该字段，定位是否为内存问题。
配置改完后发现没生效
pm2配置文件的修改,需要重新加载才会生效，只改文件不重启进程是没用的，执行：
pm2 restart ecosystem.config.js --env production
想稳妥一些,先执行
pm2 delete ecosystem.config.js 删掉旧进程，再执行 pm2 start ecosystem.config.js --env production 重新启动，删除再启动的方式能彻底清除旧配置的残留。
用table对比命令行启动与配置文件
| 对比项 | 命令行启动 | pm2配置文件 |
|---|---|---|
| 可读性 | 命令一长串，参数混在一起 | 结构化字段，一目了然 |
| 可维护性 | 参数在脚本或文档里 | 配置作为代码进仓库，有版本管理 |
| 多环境支持 | 需要写多个启动脚本 | env 和 env_production 天然支持 |
| 团队协作 | 新成员需要问老成员启动方式 | clone代码后看配置文件即可 |
| 扩展性 | 每加一个参数，命令更长 | 字段定义清晰，新参数按文档加 |
| 排错成本 | 参数写错不易察觉 | 配置项写错，pm2启动时报错提示 |
高频Q&A
pm2配置文件和生产环境的systemd冲突吗
两者可以共存,pm2的 pm2 startup 命令生成的启动脚本底层就是systemd服务，只是把pm2的守护进程托管给了systemd，生产环境使用systemd直接管理Node.js进程也是常见做法，区别在于systemd要求手写Unit文件，逻辑直白但缺少pm2的自动重启、负载均衡、日志轮转等现成能力，多数情况下用pm2管理应用进程，用systemd管理pm2本身。
pm2配置文件怎么给多个项目共用
每个项目维护一个独立的 ecosystem.config.js，用 pm2 start 时分文件加载即可，若想用一个文件管理多个项目，在 apps 数组里配置多个对象：
module.exports = {
apps: [
{
name: 'api-server',
script: './api/index.js'
},
{
name: 'worker-server',
script: './worker/index.js'
}
]
}
但项目之间的依赖版本、环境变量差异较大时，还是建议按项目拆分文件，避免逻辑耦合。
pm2配置文件里环境变量和.env文件怎么配合
pm2配置文件支持通过 env 字段注入变量，也支持读取 .env 文件，在配置文件顶部引入dotenv：
require('dotenv').config();
module.exports = {
apps: [
{
name: 'my-app',
script: './src/index.js',
env: {
NODE_ENV: process.env.NODE_ENV || 'development',
DB_HOST: process.env.DB_HOST
}
}
]
}
这样 .env 文件里的变量直接映射到配置文件中的 env 对象，代码里的 process.env.DB_HOST 就能正常读取，注意 .env 文件不应该提交到git仓库，只保留 .env.example 作为模板。
配置文件是pm2使用中的关键环节,把启动逻辑固化进仓库，团队协作时少踩很多坑，多环境部署、日志切割、自动重启这几个点配置到位，生产环境的稳定性就有了基础保障。