NVM으로 Node 버전 관리하기

문제 상황

프로젝트 초기 세팅을 마치고, 팀원들이 저의 개발 환경을 기반으로 작업을 시작하려던 중 아래와 같은 메시지를 받았습니다.

처음 보는 오류라 구글링을 해보니, CommonJS (require)와 ES Module (import)의 충돌로 인해 발생하는 문제로, 이를 해결하기 위해 package.json에 "type": "module"을 지정해야 한다는 내용을 확인했습니다.

그런데 이미 package.json에는 type: "module"이 설정되어 있었습니다.

이상했던 점은 제 로컬에서는 아무 문제 없이 잘 작동했지만, 팀원 두 명 모두 동일한 오류를 겪고 있다는 점이었습니다. 즉, 코드 문제가 아닌, 로컬 환경 차이에서 비롯된 문제일 가능성이 높아졌습니다.

환경 차이를 따져봤을 때 가장 의심스러운 것은 Node.js 버전이었습니다. 각자의 Node 버전을 확인해보니 다음과 같았습니다.

결과적으로, Node 23 버전 이상에서만 문제가 발생하지 않았고, 팀원들이 Node를 업그레이드하자 오류가 해결되었습니다.

하지만 Node 20, 22는 보통 안정 버전이라 문제 없이 작동해야 할 텐데, 왜 이럴까 하는 의문이 남았습니다.

제가 진행했던 초기 세팅은 React Router + Vite를 기반으로 했습니다. 문서상 최소 요구 Node 버전은 다음과 같았습니다:

정상적으로 동작해야 할 버전이었지만, 실제로 여러 Node 버전에서 테스트해본 결과:

혹시 저만 이런 문제를 겪고 있는지 찾아보던 중, 다음 이슈를 발견했습니다:

이슈를 살펴보면, Node 23 이상에서만 작동하는 문제가 실제로 존재하고 있으며, 아직 해결되지 않은 상태입니다.

저희는 최신 기술 스택을 유지하고자 Node를 업그레이드하는 방향을 선택했습니다.

그런데 팀원 모두가 로컬에 직접 Node를 설치하고, 수시로 버전을 변경하는 것은 번거롭고 비효율적입니다.

이를 위해 활용할 수 있는 것이 바로 NVM입니다.

NVM(Node Version Manager)은 여러 버전의 Node.js를 손쉽게 설치하고 전환할 수 있게 해주는 도구입니다.

Node.js 버전을 자유롭게 설치하고 전환할 수 있도록 도와주는 CLI 도구입니다.

협업 시 팀원들의 Node 버전이 다르면 의도치 않은 오류가 발생할 수 있습니다. NVM을 사용하면 .nvmrc 파일을 통해 팀원들이 동일한 버전을 사용하도록 강제할 수 있습니다.

nvm install, nvm use 명령어 한 줄로 버전을 전환할 수 있어, 복잡한 설치/삭제 과정 없이 간편합니다.

기존 방식대로 설치한 Node는 시스템 전체에 영향을 미치지만, NVM은 로컬 사용자 기준으로 관리됩니다.

터미널에서 아래 명령어를 입력해 NVM을 설치합니다:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

설치가 완료되면, 터미널을 재시작하거나 다음 명령어로 NVM을 활성화합니다:

source ~/.nvm/nvm.sh

정상적으로 설치되었는지 확인하려면:

nvm --version

버전이 출력되면 성공적으로 설치된 것입니다.

이제 프로젝트 루트에서 아래 명령어를 실행해 Node 버전을 설정하면 됩니다.

nvm install    # .nvmrc에 명시된 버전(v23.10.0) 설치
nvm use        # 해당 버전으로 Node 환경 전환

저희 팀은 Node.js 버전 차이로 인한 문제를 방지하기 위해 .nvmrc 파일을 프로젝트 루트에 추가하고, Node.js의 최신 버전인 v23.10.0을 명시했습니다.

이 설정을 통해 모든 팀원이 같은 Node 환경에서 개발할 수 있게 되었고, 버전 차이로 인한 예기치 못한 오류도 사전에 방지할 수 있게 되었습니다.

관련 내용은 이 PR을 통해 공유했으며, 팀원들이 쉽게 확인하고 반영할 수 있도록 문서화해두었습니다.

협업을 할 때 사소해 보이는 환경 차이가 예상치 못한 오류를 만들기도 합니다. NVM을 잘 활용하면 이런 문제를 깔끔하게 예방할 수 있으니 꼭 도입해보시길 추천드립니다!