Node.js 버전 충돌 날 때, 맥 NVM으로 깔끔하게 관리!

A 프로젝트에서는 Node.js 16을 써야 하고, B 프로젝트에서는 Node.js 18이 필수인데 터미널에서 늘 다른 버전이 실행되어 답답하셨나요? 분명 특정 프로젝트에 맞는 버전을 설정했는데도, 다른 프로젝트를 실행하면 Node.js 버전 충돌 오류가 뜨는 경험, 개발자라면 한 번쯤 겪어봤을 겁니다.

이런 문제는 여러 프로젝트가 각각 다른 Node.js 버전을 요구할 때, 시스템 전역에 설치된 Node.js 버전이 충돌하면서 발생합니다. 즉, 각 프로젝트의 환경을 독립적으로 관리하지 못하기 때문입니다.

이 글에서는 Node.js 버전 관리 도구인 NVM(Node Version Manager)을 맥 환경에 깔끔하게 설치하고, 여러 Node.js 버전을 원하는 대로 전환하며, 심지어 프로젝트별로 특정 Node.js 버전을 고정하는 구체적인 방법을 단계별로 설명합니다.

Node.js 버전 충돌, 왜 발생할까요?

최신 웹 개발 환경에서는 다양한 라이브러리와 프레임워크가 빠르게 변화하며, 이들은 각기 다른 Node.js 버전을 요구하는 경우가 많습니다. 예를 들어, 어떤 프로젝트는 안정성을 이유로 Node.js 16.x 버전을 고수하고, 다른 프로젝트는 최신 기능을 활용하기 위해 Node.js 18.x 버전이나 20.x 버전을 필요로 합니다.

문제는 시스템에 Node.js를 하나만 전역으로 설치할 경우, 특정 버전이 필요한 프로젝트에서 예상치 못한 오류를 발생시킨다는 점입니다. npm 패키지 설치 실패부터 애플리케이션 실행 오류까지, 버전 불일치는 개발 생산성을 심각하게 저해하는 주범입니다. 전 세계 개발자의 약 80%가 적어도 한 번 이상 Node.js 버전 문제로 시간을 낭비했다는 통계도 있습니다.

이러한 문제를 해결하기 위해 NVM(Node Version Manager) 같은 버전 관리 도구가 등장했습니다. NVM은 여러 Node.js 버전을 시스템에 독립적으로 설치하고, 필요에 따라 손쉽게 전환할 수 있도록 도와줍니다. 이는 개발자가 프로젝트 요구사항에 맞춰 유연하게 개발 환경을 구성할 수 있게 합니다.

맥에 NVM 설치, 단 5분이면 충분합니다

NVM을 맥에 설치하는 과정은 매우 간단하며, 몇 가지 터미널 명령어만으로 빠르게 완료할 수 있습니다. 아래 5단계만 따라오시면 NVM을 바로 사용할 수 있습니다. 기존에 Node.js가 설치되어 있다면 먼저 삭제하는 것을 권장하지만 필수는 아닙니다.

1. 설치 스크립트 실행 — NVM 공식 GitHub에서 제공하는 설치 스크립트를 실행합니다. 터미널을 열고 다음 명령어를 입력하세요.

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

   설치 스크립트는 NVM 저장소를 클론하고 환경 변수를 `.bash_profile`, `.zshrc`, `.profile`, 또는 `.bashrc` 파일에 자동으로 추가합니다.

2. 환경 변수 설정 확인 — 설치 스크립트가 환경 변수를 추가한 후, 터미널을 다시 시작하거나 다음 명령어를 실행하여 변경 사항을 적용해야 합니다. 일반적으로 macOS Ventura 이상에서는 기본 셸이 Zsh이므로 `.zshrc` 파일을 사용합니다.

   source ~/.zshrc

   만약 Bash 셸을 사용한다면 `source ~/.bash_profile` 또는 `source ~/.bashrc`를 사용하세요.

3. NVM 설치 확인 — NVM이 제대로 설치되었는지 확인하기 위해 다음 명령어를 입력합니다.

   nvm --version

   버전 정보가 출력된다면 NVM이 성공적으로 설치된 것입니다.

4. LTS 버전 목록 확인 — 설치 가능한 LTS(Long Term Support) 버전 목록을 확인하여 어떤 Node.js 버전을 설치할지 결정합니다.

   nvm ls-remote --lts

   이 명령어를 통해 안정적인 버전들을 확인할 수 있습니다.

5. 첫 Node.js 버전 설치 — 이제 NVM을 이용해 원하는 Node.js 버전을 설치할 차례입니다. 예를 들어, Node.js 18 LTS 버전을 설치하려면 다음 명령어를 사용합니다.

   nvm install 18

   설치가 완료되면 자동으로 해당 버전이 현재 사용 버전으로 설정됩니다.

NVM으로 Node.js 버전 자유롭게 오가기

NVM이 설치되었다면 이제 Node.js 버전을 자유롭게 설치하고 관리할 수 있습니다. 여러 버전을 오가며 작업하는 것이 NVM의 가장 큰 장점입니다. 다음 세 가지 핵심 명령어로 능숙하게 Node.js 버전을 관리해 보세요.

1. 다른 Node.js 버전 설치 — 추가적인 Node.js 버전이 필요하다면 `nvm install` 명령어를 다시 사용합니다. 예를 들어 Node.js 16 버전을 설치하려면:

   nvm install 16

   특정 패치 버전까지 지정하려면 `nvm install 16.14.0`처럼 사용할 수도 있습니다.

2. 설치된 Node.js 버전 확인 및 전환 — 현재 시스템에 설치된 모든 Node.js 버전을 확인하려면 `nvm ls` 명령어를 사용합니다.

   nvm ls

   출력된 목록에서 원하는 버전으로 전환하고 싶다면 `nvm use` 명령어를 사용합니다. 예를 들어 Node.js 16으로 전환하려면:

   nvm use 16

   이렇게 전환하면 현재 터미널 세션에서만 해당 버전이 적용됩니다.

3. 프로젝트별 Node.js 버전 자동 설정 (.nvmrc) — 가장 강력한 기능 중 하나는 프로젝트 디렉토리에서 자동으로 특정 Node.js 버전을 사용하도록 설정하는 것입니다. 프로젝트 루트 디렉토리에 `.nvmrc`라는 파일을 생성하고, 그 안에 사용할 Node.js 버전을 명시하면 됩니다.

   echo "18" > .nvmrc

   이 파일을 생성한 후, 해당 프로젝트 디렉토리로 이동하여 `nvm use` 명령어를 실행하면 `.nvmrc` 파일에 명시된 버전으로 Node.js가 자동으로 전환됩니다. 이는 프로젝트 A에서는 Node.js 16, 프로젝트 B에서는 Node.js 18을 사용하는 상황에서 빛을 발합니다.

NVM 사용, 이것만 알면 고수가 됩니다

NVM을 효율적으로 사용하기 위한 몇 가지 팁과 주의사항을 알려드립니다. 이 내용들을 숙지하시면 개발 환경을 더욱 안정적이고 편리하게 관리할 수 있을 겁니다.

추가적으로 NVM의 별칭(alias) 기능을 활용하면 더욱 편리합니다. 예를 들어, 특정 Node.js 버전을 시스템의 기본(default) 버전으로 설정할 수 있습니다. `nvm alias default 18` 명령어를 사용하면 터미널을 새로 열었을 때 자동으로 Node.js 18이 활성화됩니다. 또한, 더 이상 사용하지 않는 Node.js 버전을 삭제하고 싶다면 `nvm uninstall [버전]` 명령어를 사용하면 됩니다.

정기적으로 NVM 자체를 업데이트하는 것도 중요합니다. `nvm self-update` 명령어나, 처음 설치했던 스크립트를 다시 실행하여 최신 NVM 기능을 활용하고 잠재적인 버그를 해결할 수 있습니다. NVM 업데이트는 약 3개월에 한 번 정도 확인해주는 것이 좋습니다.