nvm으로 Node.js 버전업 후 Nginx 502 문제 해결하기

1. Node.js 버전 관련 문제 발생

이전 글에서 NCP 서버에 Next.js를 배포할 때 apt로 Node.js를 설치했다고 했는데, 여기에서 언급했던 이슈에 대해 작성해보려고 한다.

배포 사이트에 접속했더니 502 Bad Gateway가 뜨는 문제가 생겼다.

배포 서버에서 발생한 502 에러

처음에는 Nginx 문제인 줄 알았는데 SSH 접속 후 pm2 list로 확인해보니 prod 프로세스의 status가 errored였다.

PM2 프로세스 리스트

pm2 logs로 최근 로그 확인 후 원인을 알 수 있었다.

You are using Node.js 18.19.1. For Next.js, Node.js version ">=20.9.0" is required.

React 보안 이슈로 Next.js 버전을 올리면서 요구하는 Node.js 최소 버전도 올라간 것 같았다.

 

---

2. nvm으로 Node.js 업그레이드

nvm을 설치해서 Node.js 버전을 올렸다.

# 1. nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 2. 셸 설정 새로고침
source ~/.zshrc

# 3. nvm 설치 확인
nvm --version

# 4. Node.js 20 설치 및 설정
nvm install 20
nvm use 20
nvm alias default 20

# 5. 버전 확인
node -v

이후 프로젝트 의존성 재설치 및 빌드, PM2 재시작까지 했다.

cd ~/project-prod
rm -rf node_modules package-lock.json
npm install
npm run build
cd ..
pm2 restart prod

그런데 얼마 후 똑같은 오류가 다시 발생했다 🥲

 

---

3. PM2가 버전업된 Node.js를 인식하지 못하는 원인 찾기

node -v를 치면 분명 v20이 나왔다. 그런데 왜 PM2는 여전히 Node.js 18을 쓰고 있는 걸까?!

pm2 describe prod 명령어로 프로세스 상세 정보를 확인해봤다. 하단에 Divergent env variables from local env 항목이 보이는데, PM2 프로세스가 갖고 있는 환경변수와 현재 셸의 환경변수가 다르다는 걸 알려주는 부분이다.

PM2 프로세스와 현재 셸에서 다른 환경변수들

둘의 PATH가 달랐다. 현재 셸은 nvm 경로를 갖고 있었지만, PM2 데몬은 nvm 설치 이전의 PATH를 그대로 갖고 있었다.

# describe에서 보이는 PM2의 환경변수
# /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:...

# 실제 셸의 환경변수
echo $PATH
# /root/.nvm/versions/node/v20.19.6/bin:/usr/local/sbin:...

PM2는 처음 실행된 시점의 환경변수를 유지한다. nvm을 나중에 설치해서 PATH가 바뀌어도 이미 떠 있는 PM2 데몬은 변경 사항을 반영하지 않는다.

PM2 - Startup Script

When you upgrade the local Node.js version, be sure to update the PM2 startup script, so it runs the latest Node.js binary you have installed.

 

---

4. PM2 startup 스크립트 업데이트

간단하게 다음 명령어를 이용해서 바뀐 환경을 반영할 수 있다고 되어있다.

# 기존 설정 제거
pm2 unstartup

# 새로운 설정 반영
pm2 startup

PM2를 완전히 종료하고 시작하는 방법도 있다. 사실 나는 이렇게 해결했는데 뒤늦게 공식 문서 설명을 발견했다 ㅎ

pm2 kill
pm2 start npm --name "prod" -- start

이렇게 하니 Divergent env variables from local env 항목에서 PATH 부분이 사라졌고, 다음부터 버전 오류가 뜨지 않았다.

다음부터는 처음 Node.js를 설치할 때 nvm으로 설치하는게 좋을 것 같다!