프로젝트마다 Node.js 버전 다를 때, 맥 nvm으로 해결!

맥에서 여러 프로젝트를 동시에 진행하며 각기 다른 Node.js 버전을 필요로 할 때마다 수동으로 버전을 전환하거나, 예상치 못한 충돌로 인해 답답함을 느끼셨을 겁니다. 이런 문제는 Node.js 버전 간의 의존성 차이로 인해 발생하며, 개발 환경의 안정성을 해치고 작업 효율을 크게 떨어뜨립니다.

이 글에서는 nvm(Node Version Manager)을 활용하여 맥 환경에서 Node.js 버전을 효율적으로 설치하고 관리하며, 각 프로젝트 요구사항에 맞춰 간편하게 전환하는 구체적인 방법을 단계별로 알려드립니다.

nvm, 왜 필요한가요?

웹 개발 생태계는 빠르게 변화하고 있으며, 이는 Node.js 버전에도 그대로 적용됩니다. 최신 프레임워크는 최신 Node.js 버전을 요구하고, 몇 년 전 만들어진 레거시 프로젝트는 특정 구형 버전에서만 안정적으로 작동하는 경우가 허다합니다. 이때 하나의 Node.js 버전만 설치되어 있다면, 매번 새로운 프로젝트를 시작할 때마다 기존 버전을 삭제하고 재설치하는 비효율적인 과정을 반복해야 합니다.

수동으로 버전을 관리하는 것은 매우 번거로울 뿐만 아니라, 자칫 잘못하면 시스템 전체에 문제를 일으킬 수 있습니다. 특히 전역으로 설치된 패키지(npm, yarn 등)들은 Node.js 버전에 따라 호환성 문제가 발생하기 쉬워, 개발 환경이 불안정해지는 주요 원인이 됩니다. 이런 문제를 해결하기 위해 Node.js 버전을 격리하고 유연하게 전환할 수 있는 도구가 절실합니다.

Photo by RealToughCandy.com on Pexels

맥에 nvm 설치하기 (단 3단계)

nvm을 맥에 설치하는 과정은 놀라울 정도로 간단합니다. 터미널 명령어를 통해 nvm 스크립트를 다운로드하고, 셸 환경에 nvm을 로드하도록 설정하는 것이 전부입니다. 이 과정을 거치면 앞으로 여러분의 Node.js 버전 관리는 90% 이상 개선될 것입니다.

1. nvm 설치 스크립트 실행 — 터미널을 열고 아래 명령어 중 하나를 실행하여 nvm을 다운로드하고 설치합니다. 일반적으로 curl을 선호합니다.

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

   또는 wget 사용:

   wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

   주의
   위 URL의 버전(v0.39.7)은 nvm의 최신 버전이 아닐 수 있습니다. nvm 공식 GitHub 페이지(github.com/nvm-sh/nvm)에서 최신 버전 스크립트 URL을 확인하고 사용하는 것이 좋습니다.
2. 셸 환경 설정 파일 업데이트 — 설치 스크립트가 완료되면, nvm을 셸에 로드하기 위해 .zshrc, .bash_profile, 또는 .profile 파일에 아래 내용을 추가해야 합니다. 여러분이 사용하는 셸에 따라 파일을 선택하세요. macOS Catalina 이후 버전은 대부분 .zshrc를 사용합니다.

   export NVM_DIR="$HOME/.nvm"
   [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
   [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion

   nano ~/.zshrc 또는 vi ~/.bash_profile 명령어로 파일을 열어 내용 추가 후 저장합니다.

3. 셸 재시작 또는 소스 적용 — 변경된 설정 파일을 적용하기 위해 터미널을 완전히 닫았다가 다시 열거나, 다음 명령어를 실행합니다.

   source ~/.zshrc

   이제 터미널에 nvm --version을 입력했을 때 버전 정보가 출력되면 성공적으로 설치된 것입니다. 만약 command not found 오류가 발생한다면, 위 단계를 다시 한번 꼼꼼히 확인해 보세요.

Photo by Rodolfo Quirós on Pexels

nvm으로 Node.js 버전 관리 핵심 명령어

nvm 설치를 완료했다면 이제 Node.js 버전을 자유롭게 설치하고 전환할 준비가 된 것입니다. nvm은 몇 가지 직관적인 명령어로 모든 버전 관리 작업을 수행할 수 있도록 설계되어 있습니다. 이 명령어들을 익히면 단 5분 안에 어떤 프로젝트든 시작할 준비를 마칠 수 있습니다.

1. 설치 가능한 Node.js 버전 확인 — 설치하기 전에 어떤 버전들이 있는지 확인하는 것이 좋습니다.

   nvm ls-remote

2. 특정 Node.js 버전 설치 — 원하는 버전 번호를 지정하여 설치합니다. 예를 들어, 18.18.0 버전을 설치하려면:

   nvm install 18.18.0

   최신 LTS(Long Term Support) 버전을 설치하려면 nvm install --lts 명령어를 사용합니다. 이는 안정적인 개발 환경을 위해 강력히 추천됩니다.

3. 설치된 Node.js 버전 확인 — 현재 시스템에 설치된 모든 Node.js 버전을 목록으로 볼 수 있습니다.

   nvm ls

   현재 활성화된 버전은 목록에서 화살표(->)로 표시됩니다.

4. Node.js 버전 전환 — 특정 버전으로 전환하고 싶을 때 사용합니다. 예를 들어, 18.18.0 버전으로 전환하려면:

   nvm use 18.18.0

5. 기본(default) Node.js 버전 설정 — 새로운 터미널을 열었을 때 자동으로 활성화될 버전을 지정합니다.

   nvm alias default 18.18.0

6. Node.js 버전 제거 — 더 이상 필요 없는 버전을 깔끔하게 삭제합니다.

   nvm uninstall 16.14.2

Photo by cottonbro studio on Pexels

프로젝트별 Node.js 버전 자동 전환 (.nvmrc 활용)

nvm의 가장 강력한 기능 중 하나는 .nvmrc 파일을 사용하여 프로젝트 디렉토리 진입 시 Node.js 버전을 자동으로 전환하는 기능입니다. 이 기능을 활용하면 수십 개의 프로젝트를 오가면서도 단 한 번의 설정으로 모든 버전 관리 고민을 해결할 수 있습니다.

.nvmrc 파일은 단순한 텍스트 파일로, 프로젝트가 필요로 하는 Node.js 버전 번호만 명시하면 됩니다. 예를 들어, 프로젝트가 Node.js 16.14.2 버전을 사용해야 한다면, 프로젝트의 루트 디렉토리에 .nvmrc 파일을 생성하고 그 안에 16.14.2라고만 작성하면 됩니다.

1. .nvmrc 파일 생성 — 프로젝트의 루트 디렉토리에서 다음 명령어를 실행하여 .nvmrc 파일을 만들고 원하는 버전을 입력합니다.

   echo "16.14.2" > .nvmrc

   이때 입력하는 버전은 이미 nvm으로 설치되어 있어야 합니다. 설치되어 있지 않다면 nvm install 16.14.2 명령어로 먼저 설치하세요.

2. 자동 전환 활성화 — .nvmrc 파일이 준비되었다면, 해당 프로젝트 디렉토리에서 nvm use 명령어를 실행합니다. nvm은 .nvmrc 파일을 감지하고 자동으로 지정된 Node.js 버전으로 전환합니다.

   nvm use

   만약 자동으로 nvm use를 실행하고 싶다면, 셸 설정 파일(예: .zshrc)에 다음 라인을 추가하여 cd 명령어가 실행될 때마다 버전을 확인하도록 할 수 있습니다. 이 방법을 사용하면 프로젝트 디렉토리로 이동하는 순간 즉시 해당 Node.js 버전이 활성화됩니다.

   autoload -U add-zsh-hook
   add-zsh-hook chpwd nvm_auto_use