다양한 프로젝트에서의 Node.js 버전 격리 필요성

현대 웹 개발 환경에서는 각 프로젝트가 서로 다른 Node.js 버전을 요구하는 경우가 흔합니다. 예를 들어, 일부 프로젝트는 Node.js 14에 의존하고, 다른 프로젝트는 18 이상의 최신 버전이 필요할 수 있습니다. 직접 여러 버전을 설치하고 삭제하는 방식은 번거롭고, 시스템 환경을 혼란스럽게 만들 수 있습니다.

Node Version Manager (NVM)는 이러한 문제를 해결하기 위해 설계된 명령줄 도구입니다. 하나의 시스템 내에서 여러 버전의 Node.js를 설치하고, 필요에 따라 쉽게 전환할 수 있도록 지원합니다.

• nvm-sh: 공식 리포지토리 – GitHub
• nvm-windows: Windows용 독립형 빌드 – GitHub

NVM의 작동 원리

NVM의 핵심 기능은 간결하면서도 효과적인 환경 분리입니다:

1. 버전 격리: 각 Node.js 버전은 별도 디렉터리에 설치되어 상호 간 충돌을 방지합니다.
2. PATH 조정: 활성화된 버전에 따라 시스템의 PATH 변수를 수정하여 해당 버전의 실행 파일 경로를 우선순위로 설정합니다.
3. 심볼릭 링크 사용: Unix 계열 운영체제에서는 현재 활성화된 버전을 가리키는 심볼릭 링크를 생성합니다. Windows에서는 실제 환경 변수를 변경합니다.
4. 버전 자동 감지: 프로젝트 루트에 존재하는 .nvmrc 파일이나 명령행 옵션을 통해 사용할 버전을 결정합니다.

예를 들어, nvm use 16.14.0 명령을 실행하면, NVM은 해당 버전의 바이너리 디렉터리를 찾아서 PATH에 추가하고, 심볼릭 링크를 업데이트합니다. 이후 node 또는 npm 명령어는 항상 현재 선택된 버전을 사용하게 됩니다.

설치 및 초기 설정

Linux/macOS 시스템

공식 설치 스크립트를 사용해 설치합니다:

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

설치 후, 쉘 설정 파일(~/.bashrc, ~/.zshrc, ~/.profile)에 다음 내용을 추가합니다:

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

변경 사항을 적용하려면:

source ~/.bashrc

Windows 시스템

Windows 사용자는 nvm-windows를 사용해야 합니다:

1. 기존 Node.js 설치 제거
2. 최신 릴리스 페이지에서 nvm-setup.zip 다운로드
3. 설치 프로그램 실행 및 안내에 따라 설치
4. 관리자 권한으로 명령 프롬프트 또는 PowerShell 열기

설치 확인

정상 설치 여부를 확인하려면 다음 명령어를 실행합니다:

nvm --version

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

기본 명령어 사용법

Node.js 버전 설치

# 최신 LTS 버전 설치
nvm install --lts

# 최신 메이저 버전 설치
nvm install latest

# 특정 버전 설치
nvm install 16.14.0
nvm install 14.19.0

설치된 버전 목록 확인

nvm list

버전 전환

# 특정 버전으로 전환
nvm use 16.14.0

# 최신 LTS 버전 사용
nvm use --lts

# 시스템 기본 버전 사용 (설치된 경우)
nvm use system

기본 버전 설정

nvm alias default 16.14.0

새 터미널을 열 때마다 이 버전이 자동으로 활성화됩니다.

프로젝트별 버전 지정

프로젝트 루트에 .nvmrc 파일을 생성하고 버전 번호를 기록하세요:

echo "16.14.0" > .nvmrc

그 후, 다음 명령어로 자동 전환:

nvm use

네트워크 문제 발생 시 수동 설치 방법

다운로드 실패 시 수동으로 설치할 수 있습니다.

1. Node.js 공식 배포 페이지에서 필요한 버전(예: v16.14.0) 다운로드
2. 운영체제에 맞는 압축 파일 선택:
   • Windows: node-v16.14.0-win-x64.zip
   • Linux: node-v16.14.0-linux-x64.tar.xz
   • macOS: node-v16.14.0-darwin-x64.tar.gz
3. NVM 설치 경로에 해제:
   • Linux/macOS: ~/.nvm/versions/node
   • Windows: %APPDATA%\nvm
4. 해당 버전 폴더 생성 후 압축 파일 해제
5. 디렉터리 이름 정리 (예: v16.14.0로)

Unix 계열에서 심볼릭 링크 수동 생성 (선택 사항)

cd ~/.nvm/versions/node/v16.14.0
ln -s node-v16.14.0-linux-x64/* .

수동 설치 검증

nvm list
nvm use 16.14.0
node --version

출력 결과가 v16.14.0이면 성공입니다.

주요 오류 및 해결 방법

Q1: nvm 명령어를 찾을 수 없습니다

원인: 쉘 설정 파일에 초기화 스크립트가 누락됨.

해결:

1. 설정 파일에 source ~/.nvm/nvm.sh 포함 여부 확인
2. source ~/.zshrc 또는 source ~/.bashrc로 재로드
3. NVM_DIR 변수가 올바른 경로인지 점검

Q2: 버전 전환 후에도 node -v가 오래된 버전 표시

원인: 시스템에 다른 Node.js 설치가 중복 존재하거나 캐시 문제.

해결:

1. which node (Linux/macOS) 또는 where node (Windows)로 실제 경로 확인
2. 기존 설치 제거 또는 터미널 재시작

Q3: Windows에서 권한 오류 발생

해결:

1. 관리자 권한으로 터미널 실행
2. NVM 설치 디렉터리의 접근 권한 확인

Q4: 스크립트 내에서 nvm 사용 불가

해결:

source ~/.nvm/nvm.sh
nvm use 16

또는:

nvm exec 16 node script.js

Q5: Checksum does not match 오류

해결:

1. nvm cache clear 실행
2. 재시도
3. 지속적일 경우 수동 설치 고려

Q6: .nvmrc 파일이 자동 전환되지 않음

해결:

1. .nvmrc 파일에 버전만 포함되었는지 확인
2. avn 도구 설치로 자동 전환 가능:

   npm install -g avn avn-nvm
       avn setup
       

Q7: NVM 완전 제거

절차:

1. 설치 폴더 삭제:
   • Linux/macOS: rm -rf ~/.nvm
   • Windows: nvm-windows 제거 + %APPDATA%\nvm 삭제
2. 쉘 설정 파일에서 관련 코드 제거
3. 잔여 Node.js 환경 변수 삭제

고급 기능 및 팁

별칭을 통한 버전 관리 단순화

nvm alias my-project 16.14.0
nvm use my-project
nvm alias

멀티프로젝트 환경에서 자동 전환 구성

다음과 같이 자동화할 수 있습니다:

1. 각 프로젝트 루트에 .nvmrc 파일 작성
2. Zsh 사용자라면 zsh-nvm 플러그인 설치
3. 또는 direnv 도구를 사용해 커밋 시 자동 환경 설정

CI/CD 파이프라인 통합 예시

before_script:
  - curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
  - source ~/.nvm/nvm.sh
  - nvm install 16
  - nvm use 16