PM2에서 ecosystem.config.js를 사용하는 이유와 장점

PM2는 Node.js 애플리케이션을 관리하기 위한 강력한 프로세스 매니저이다. PM2는 실행 환경을 구성할 수 있도록 ecosystem 파일 방식을 제공한다. 이 구성 파일은 두 가지 형태로 작성할 수 있다.

• JSON 형식 (ecosystem.json)
• JS 모듈 형식 (ecosystem.config.js)

이 문서에서는 ecosystem.config.js 파일을 사용하는 이유, 장점, 그리고 추가적으로 활용할 수 있는 기능에 대해 얘기하고자 한다.

---

1. ecosystem.config.js vs ecosystem.json

JSON 파일 사용 시 특징

• 구조가 단순하여 자동 생성하기 쉬움
• 정적(static) 설정만 가능
• 주석을 작성할 수 없음
• 환경 변수 하드코딩 필요

JS 모듈 사용 시 특징

• Node.js 문법을 사용할 수 있어 유연함
• 조건문, 외부 모듈 import, 동적 환경 변수 처리 가능
• .env 로드 가능 (dotenv 활용)
• 주석 작성 가능 → 가독성과 협업에 유리

// ecosystem.config.js 예시
require('dotenv').config();

module.exports = {
  apps: [
    {
      name: 'my-app',
      script: 'dist/main.js',
      env: {
        NODE_ENV: process.env.NODE_ENV || 'development',
        PORT: process.env.PORT || 3000,
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 8080,
      },
    },
  ],
};

---

2. JS 모듈 방식 (ecosystem.config.js)의 장점

기능 설명

환경에 따라 분기	process.env.NODE_ENV에 따라 실행 설정 분기 가능
동적 포트 지정	환경 변수 존재 여부에 따라 기본값 지정 가능
주석	설정 파일 내 설명 주석 작성 가능
외부 모듈 활용	dotenv, fs, path 등 Node 모듈 사용 가능
복잡한 조건 처리	if 문 등 조건문을 활용한 설정 구성 가능

---

3. ecosystem.config.js를 통해 활용 가능한 기능들

여러 앱 동시에 실행 (Multi-App)

apps: [
  { name: 'app1', script: 'app1.js' },
  { name: 'app2', script: 'app2.js' }
]

클러스터 모드로 실행

instances: 'max',
exec_mode: 'cluster'

환경별 설정

env: { NODE_ENV: 'development' },
env_production: { NODE_ENV: 'production' }

로그 파일 설정

error_file: './logs/error.log',
out_file: './logs/output.log'

watch 모드 (파일 변경 시 재시작)

watch: true,
ignore_watch: ['node_modules', 'logs']

cron 리스타트 설정

cron_restart: '0 0 * * *'  // 매일 자정 재시작

Pre/Post 스크립트 실행

pre_start: 'echo Starting...',
post_stop: 'echo Stopped.'

---

4. 실행 예시

# 기본 실행
pm2 start ecosystem.config.js

# production 환경으로 실행
pm2 start ecosystem.config.js --env production

# 앱 이름으로 제어
pm2 restart my-app
pm2 stop my-app
pm2 delete my-app

---

마무리

ecosystem.config.js는 단순한 환경 변수 전달을 넘어서서 환경 분기, 다중 앱 실행, 로그 관리, 클러스터링 등 다양한 기능을 활용할 수 있도록 해준다. 특히, dotenv를 함께 사용하면 .env 파일로부터 안전하고 유연하게 환경 변수를 주입할 수 있어 실무에서 매우 유용하게 쓰일 수 있다.

따라서 복잡한 설정이나 운영 자동화를 고려할 때 ecosystem.config.js 을 적극 활용하자.