프로젝트마다 Node.js 버전이 다를 때? nvm 맥으로 한 번에 관리!

여러 Node.js 프로젝트를 동시에 작업하는데 각기 다른 Node.js 버전을 요구해서 매번 수동으로 변경하거나 예기치 않은 에러가 발생하는 상황, 개발자라면 한 번쯤 겪어보셨을 겁니다.

이러한 문제는 Node.js 생태계의 빠른 발전과 하위 호환성 문제 때문에 발생하며, 개발 환경 설정에 불필요한 시간을 소모하게 만듭니다.

이 글에서는 macOS 환경에서 NVM(Node Version Manager)을 활용하여 Node.js 버전을 효율적으로 설치하고, 프로젝트별로 손쉽게 전환하며 관리하는 방법을 단 5단계로 명확하게 제시합니다.

NVM (Node Version Manager) 이란 무엇인가?

NVM은 Node.js 버전을 관리하는 데 사용되는 강력한 커맨드 라인 도구입니다. 복수의 Node.js 버전을 한 시스템에 설치하고 필요에 따라 쉽게 전환할 수 있도록 돕습니다. 예를 들어, 한 프로젝트는 Node.js 14 버전을 사용하고 다른 프로젝트는 Node.js 18 버전을 필요로 할 때, NVM은 이 두 환경 사이를 매끄럽게 오갈 수 있도록 해줍니다.

이 도구가 없다면 각 프로젝트의 버전 요구사항에 맞춰 Node.js를 수동으로 제거하고 재설치하는 번거로움을 겪어야 합니다. 이는 시간 낭비는 물론, 환경 설정 오류로 이어질 가능성이 매우 높습니다. NVM은 이러한 비효율적인 과정을 단 몇 초 만에 해결해주는 핵심적인 개발 도구입니다.

Photo by Erick Ortega on Pexels

macOS에 NVM 설치 및 기본 환경 설정하기

macOS에서 NVM을 설치하는 가장 권장되는 방법은 Homebrew를 이용하는 것입니다. Homebrew는 macOS용 패키지 관리자로, 다양한 개발 도구를 쉽게 설치하고 관리할 수 있게 해줍니다. 이미 Homebrew가 설치되어 있지 않다면, 먼저 공식 웹사이트를 참조하여 설치해야 합니다.

NVM을 제대로 사용하기 위해서는 설치 후 쉘 환경 변수 설정을 완료해야 합니다. 이 과정은 NVM 명령어를 시스템이 인식하고, Node.js 버전을 올바르게 관리할 수 있도록 하는 데 필수적입니다.

1. Homebrew를 이용한 NVM 설치 — 터미널을 열고 다음 명령어를 실행합니다.
   brew install nvm
2. 환경 변수 설정 — 설치가 완료되면 NVM이 제대로 작동하도록 쉘(bash 또는 zsh) 설정 파일에 다음 내용을 추가해야 합니다.
   먼저, 설정 파일을 엽니다 (예: zsh 사용 시).
   nano ~/.zshrc
   파일의 가장 아래에 다음 내용을 추가합니다.
   export NVM_DIR=”$HOME/.nvm”
   [ -s “$(brew –prefix)/opt/nvm/nvm.sh” ] && . “$(brew –prefix)/opt/nvm/nvm.sh” # This loads nvm
   [ -s “$(brew –prefix)/opt/nvm/etc/bash_completion” ] && . “$(brew –prefix)/opt/nvm/etc/bash_completion” # This loads nvm bash_completion
   수정 후 저장하고 파일을 닫습니다. (nano 에디터에서는 Ctrl+O, Enter, Ctrl+X)
3. 쉘 재시작 또는 소스 적용 — 변경된 환경 변수를 적용하기 위해 터미널을 완전히 닫았다가 다시 열거나, 다음 명령어로 쉘 설정을 즉시 적용합니다.
   source ~/.zshrc (bash 사용 시 source ~/.bash_profile)
4. NVM 설치 확인 — 다음 명령어를 입력하여 NVM이 성공적으로 설치되었는지 확인합니다.
   nvm –version
   NVM 버전 정보가 출력되면 성공입니다.

Node.js 버전 설치하고 프로젝트에 적용하기

NVM 설치가 완료되었다면 이제 다양한 Node.js 버전을 설치하고 관리할 준비가 된 것입니다. 여러 프로젝트를 오가며 작업할 때, 필요한 Node.js 버전을 간편하게 전환하는 것이 NVM의 가장 큰 장점입니다.

특히, `.nvmrc` 파일을 활용하면 프로젝트 디렉토리로 이동할 때마다 자동으로 해당 프로젝트에 맞는 Node.js 버전으로 변경되어 개발 워크플로우를 극적으로 개선할 수 있습니다. 이는 팀 프로젝트에서 모든 개발자가 동일한 Node.js 환경에서 작업하도록 보장하여 호환성 문제를 80% 이상 줄여줍니다.

1. 사용 가능한 Node.js 버전 목록 확인 — 설치 가능한 모든 Node.js 버전을 보려면 다음 명령어를 입력합니다.
   nvm ls-remote
   이 명령은 안정적인 LTS(Long Term Support) 버전부터 최신 버전까지 다양한 옵션을 보여줍니다.
2. 특정 Node.js 버전 설치 — 원하는 버전을 설치합니다. 예를 들어, Node.js 14.17.0과 18.12.1을 설치하려면 다음과 같이 입력합니다.
   nvm install 14.17.0
   nvm install 18.12.1
   최신 안정 버전(LTS)을 설치하고 싶다면 nvm install –lts를 사용합니다.
3. 설치된 Node.js 버전 확인 — 현재 시스템에 설치된 Node.js 버전을 확인합니다.
   nvm ls
4. Node.js 버전 전환 — 특정 버전으로 전환하려면 nvm use [버전] 명령어를 사용합니다.
   nvm use 14.17.0
   전환 후 node -v를 입력하여 현재 사용 중인 버전을 확인합니다.
5. 기본 Node.js 버전 설정 — 새로운 터미널을 열 때마다 자동으로 적용될 기본 버전을 설정할 수 있습니다.
   nvm alias default 18.12.1
   이렇게 설정하면 터미널을 새로 열어도 항상 Node.js 18.12.1 버전이 기본으로 로드됩니다.
6. 프로젝트별 버전 고정 (.nvmrc) — 프로젝트 폴더 내부에 `.nvmrc` 파일을 생성하고 사용할 Node.js 버전 번호만 작성하여 저장합니다. 예를 들어, 프로젝트가 Node.js 14.17.0을 필요로 한다면:
   프로젝트 루트 폴더에서 echo “14.17.0” > .nvmrc
   이후 해당 프로젝트 폴더로 이동하여 nvm use 명령어를 입력하면, NVM이 `.nvmrc` 파일을 읽어 자동으로 해당 버전으로 전환합니다.