소프트웨어 개발 현장에서는 최신 프레임워크뿐만 아니라 과거에 구축된 레거시 프로젝트를 유지보수해야 하는 상황이 빈번합니다. 이러한 프로젝트를 로컬 환경에서 구동할 때 npm install 과정에서 예기치 못한 에러가 발생하는 경우가 많은데, 그 주요 원인 중 하나는 설치된 Node.js 버전과 프로젝트 의존성 간의 불일치입니다.
Node.js 버전 충돌 사례: node-sass
가장 대표적인 예시는 node-sass 라이브러리입니다. 예를 들어, 프로젝트에 node-sass ^4.12.0이 포함되어 있지만 개발 PC에 Node.js 16 이상의 버전이 설치되어 있다면 컴파일 에러가 발생합니다. 공식 문서에 따르면 node-sass 4.12 버전은 Node.js 12 이하의 환경에서 정상 작동하기 때문입니다.
이런 문제를 해결하기 위해 기존 Node.js를 삭제하고 새 버전을 다시 설치하는 과정은 매우 비효율적입니다. 이때 NVM(Node Version Manager) for Windows를 사용하면 여러 버전의 Node.js를 손쉽게 전환하며 관리할 수 있습니다.
NVM for Windows 설치 가이드
Windows 환경 전용 NVM은 NVM for Windows 배포 페이지에서 다운로드할 수 있습니다.
- nvm-setup.zip: 설치 마법사를 통해 간편하게 설치할 수 있는 버전입니다. 별도의 환경 변수 설정 없이 바로 사용할 수 있어 권장됩니다.
- nvm-noinstall.zip: 무설치 버전으로, 직접 환경 변수를 구성해야 합니다.
설치 과정에서 두 가지 경로를 설정하게 됩니다:
- NVM 설치 경로: NVM 프로그램 자체가 위치할 디렉토리입니다. (예:
C:\nvm) - Node.js 심볼릭 링크 경로: 현재 활성화된 Node.js 버전을 가리킬 경로입니다. (예:
C:\Program Files\nodejs)
설치가 완료되면 터미널(CMD 또는 PowerShell)을 열고 다음 명령어로 설치 여부를 확인합니다.
nvm -v주요 명령어 활용법
NVM을 통해 Node.js를 관리하는 데 필요한 핵심 명령어는 다음과 같습니다.
- 설치 가능한 버전 확인
nvm list available - 특정 버전 설치
nvm install 12.22.12 - 설치된 버전 목록 조회
nvm ls - 특정 버전 사용(전환)
nvm use 12.22.12 - 불필요한 버전 삭제
nvm uninstall 14.17.0
다운로드 속도 개선을 위한 미러 설정
Node.js 패키지 다운로드 속도가 느린 경우, 국내외 미러 서버를 설정하여 성능을 높일 수 있습니다. 터미널에서 아래 명령어를 입력하여 설정을 변경합니다.
// Node.js 미러 설정
nvm node_mirror https://npmmirror.com/mirrors/node/
// NPM 미러 설정
nvm npm_mirror https://npmmirror.com/mirrors/npm/위와 같이 설정하면 네트워크 환경에 구애받지 않고 안정적으로 원하는 버전의 Node.js 환경을 구축할 수 있습니다. NVM을 활용하면 더 이상 레거시 프로젝트의 환경 구축 문제로 시간을 낭비하지 않고 효율적인 개발이 가능해집니다.