트러블 슈팅 - PM2에서 Node.js 버전 불일치 문제 해결하기

개요

개발 서버에서 PDF 관련 작업이 갑자기 동작하지 않는 문제가 발생했다.
원인을 찾아보니 String의 replaceAll 메소드가 실행되지 않고 있었다.
처음에는 일반적인 nullable 문제로 생각하고 수정을 시도했지만, 어떤 수정을 해도 문제가 해결되지 않았다.

문제의 실마리는 Node.js 버전 불일치였다.
로컬 환경에서는 Node.js 16 버전을 사용하고 있었지만, 개발 서버는 14 버전을 사용하고 있었던 것이다. replaceAll 메소드는 Node.js 15 버전 이상에서 지원되는 기능이었다.

nvm을 통해 개발 서버의 Node.js 버전을 16으로 업데이트했지만, PM2에서 실행되는 애플리케이션은 여전히 14 버전으로 동작하는 문제가 발생했다.

문제 정의

PM2로 Node.js 애플리케이션을 실행할 때, 시스템에 설치된 Node.js 버전과 실제 실행되는 버전이 다른 상황이 발생했다.

# 시스템에 설치된 Node.js 버전
$ which node
/home/macadev/.nvm/versions/node/v16.15.0/bin/node
 
# PM2로 실행 중인 애플리케이션의 Node.js 버전 확인
$ pm2 show index | grep node
node.js version: 14.19.0

문제 원인

1. package.json의 Node.js 타입 버전 제약

{
  "devDependencies": {
    "@types/node": "^14.0.5"
  }
}

2. PM2 데몬이 이전 설정을 캐싱하고 있었을 가능성
3. Node.js 실행 경로가 명시적으로 지정되지 않은 문제

해결 과정

1차 시도: --update-env 플래그 사용

pm2 restart index --interpreter $(which node) --update-env

➡️ 실패: 여전히 Node.js 14.19.0 버전으로 실행됨

2차 시도: NODE_VERSION 환경변수 설정

NODE_VERSION=16.15.0 pm2 start server/index.js -i 2 \
  --name index --interpreter $(which node) --update-env

➡️ 실패: 버전 변경되지 않음

3차 시도: Node.js 경로 직접 지정 + 메모리 옵션 추가

NODE_OPTIONS="--max-old-space-size=4096" pm2 start server/index.js --name index -i 2 \
  --interpreter /home/macadev/.nvm/versions/node/v16.15.0/bin/node \
  -e logs/err.log -o logs/out.log \
  --node-args="--max-old-space-size=4096" \
  --update-env

➡️ 실패: 여전히 이전 버전으로 실행됨

최종 해결: PM2 완전 초기화 후 재시작

1. PM2 프로세스와 데몬 완전 종료

pm2 kill

2. 명시적 Node.js 경로 지정하여 재시작

pm2 start server/index.js --name index -i 2 \
  --interpreter ~/.nvm/versions/node/v16.15.0/bin/node \
  -e logs/err.log -o logs/out.log \
  --node-args="--max-old-space-size=4096" \
  --update-env

3. 버전 확인

$ pm2 show index | grep node
│ interpreter       │ /home/macadev/.nvm/versions/node/v16.15.0/bin/node │
│ node.js version   │ 16.15.0                                            │
│ node env          │ production                                         │

문제와 최종적으로 밝혀진 원인

1. 가장 주요한 원인: PM2 데몬의 캐시된 설정
   • PM2는 데몬 프로세스로 실행되며, 이전 설정들을 캐시하고 있었음
   • 단순히 프로세스를 재시작(restart)하거나 삭제(delete)하는 것으로는 부족
   • pm2 kill로 데몬 자체를 완전히 초기화해야 했음
2. 보조적 원인: Node.js 실행 경로가 불명확했던 문제
   • $(which node)와 같은 동적 경로 지정보다는
   • ~/.nvm/versions/node/v16.15.0/bin/node와 같이 명시적인 경로 지정이 필요했음

처음에는 package.json의 @types/node: "^14.0.5"가 원인인 것처럼 보였지만, 이는 TypeScript 타입 정의일 뿐 실제 런타임 버전과는 관계가 없었음.
실제 해결은 PM2 데몬을 완전히 초기화하고 Node.js 경로를 명시적으로 지정하는 것이었다.

결론

PM2에서 Node.js 버전을 변경할 때는 다음 사항들을 고려해야 한다:

1. PM2 데몬을 완전히 초기화(pm2 kill)해야 이전 설정이 완전히 제거된다.
2. Node.js 인터프리터 경로를 명시적으로 지정하는 것이 안전하다.
3. package.json의 의존성 버전도 실제 런타임 버전에 영향을 줄 수 있으니 주의해야 한다.
4. --update-env 플래그만으로는 환경 변경이 충분하지 않을 수 있다.

이러한 방법으로 PM2와 Node.js 버전 불일치 문제를 해결할 수 있었다.

참고

• PM2 Documentation
• Node.js Version Management