파이썬 환경을 깔끔하게 정리하고 가상환경까지 능숙하게 다루게 되었다면, 이제 웹 프론트엔드나 자바스크립트 기반의 개발 세계로 발을 들일 차례다. 웹 개발 공부를 시작하기 위해 공식 홈페이지에서 노드(Node.js)를 설치하고 터미널에서 리액트나 뷰 같은 프레임워크를 만져보려고 할 때, 초보자들이 가장 먼저 겪는 난관이 바로 패키지 관리 도구인 npm과의 버전 충돌이다.
내 컴퓨터에 깔려 있는 노드 버전은 너무 최신인데, 참고하려는 예제 코어나 강의 교재는 몇 년 전에 만들어진 구버전이라 각종 에러 문구가 터미널을 뒤덮는 광경을 마주하게 된다.
[소제목] 왜 Node.js와 npm 버전 충돌이 자주 발생하는가
노드(Node.js)는 자바스크립트를 브라우저가 아닌 컴퓨터 환경에서도 실행할 수 있게 해주는 런타임이며, 이 노드를 설치할 때 패키지 관리자인 npm(Node Package Manager)이 자동으로 함께 설치된다.
웹 생태계는 기술 변화 속도가 매우 빨라서, 라이브러리나 프레임워크의 문법과 의존성이 버전별로 크게 달라지는 경우가 많다.
전역 환경에 무조건 최신 버전의 노드만 설치해 두면, 구버전 패키지를 요구하는 프로젝트를 실행할 때 호환성 에러(ERR_REQUIRE_ESM 등)가 발생하거나 설치 자체가 거부된다.
파이썬에 가상환경이 있듯이, 자바스크립트 진영에서는 노드 버전을 프로젝트별로 유연하게 바꾸어 가며 쓸 수 있는 도구가 필수적이다.
[소제목] 노드 버전 관리자(NVM)로 버전 충돌 예방하기
이 문제를 근본적으로 해결하는 가장 현명한 방법은 컴퓨터에 노드를 직접 설치하는 대신, 노드 버전 관리자(Node Version Manager, 이하 NVM)를 사용하는 것이다. 직접 겪어본 바에 따르면 NVM을 도입한 이후로는 프로젝트마다 노드 버전을 골라 쓸 수 있어 버전 충돌 스트레스가 완전히 사라진다.
윈도우 환경에서 NVM을 활용해 개발 환경을 구축하는 기본적인 흐름은 다음과 같다.
기존에 컴퓨터에 직접 설치되어 있던 Node.js는 제어판에서 깨끗하게 삭제하는 것이 충돌을 방지하는 지름길이다.
깃허브의 공식 nvm-windows 저장소에서 최신 설치 파일(nvm-setup.exe)을 다운로드받아 설치한다.
터미널을 새로 열고 다음 명령어를 입력하여 NVM이 정상적으로 설치되었는지 확인한다. nvm version
이제 원하는 버전의 노드를 터미널 명령어 한 줄로 설치할 수 있다. 예를 들어 안정적인 LTS 버전을 설치하려면 다음과 같이 입력한다. nvm install lts
설치한 버전을 실제로 사용하겠다고 지정(활성화)하는 명령어를 입력한다. nvm use lts
이 과정을 거치면 내 컴퓨터의 메인 노드 버전이 깔끔하게 잡히며, 나중에 다른 프로젝트가 구버전 노드(예: 16버전)를 요구한다면 nvm install 16과 nvm use 16을 입력하는 것만으로 즉시 환경을 전환할 수 있다.
[소제목] 프로젝트 시작 전 package.json 확인하는 습관
NVM으로 버전을 맞추었다 하더라도, 새로운 프로젝트 폴더를 열었을 때 가장 먼저 해야 할 일은 폴더 최상단에 있는 package.json 파일을 열어보는 것이다. 이 파일 안에는 해당 프로젝트가 어떤 버전의 노드와 라이브러리를 필요로 하는지 설계도가 적혀 있다.
프로젝트를 클론받거나 다운로드받았다면, 터미널에 다음 명령어를 입력하여 필요한 라이브러리들을 일괄적으로 설치해야 한다.
npm install
여기서 주의할 점은 운영체제나 권한 문제로 인해 글로벌 패키지 설치 시 EACCES 같은 권한 에러가 발생할 수 있다는 것이다. 가급적 전역(--global) 설치보다는 프로젝트 로컬 단위로 패키지를 관리하는 습관을 들여야 시스템 오염을 막을 수 있다.
[소제목] 초보자가 자주 하는 실수와 주의사항
노드를 처음 접할 때 가장 흔히 하는 실수는 공식 홈페이지에서 무조건 가장 숫자가 높은 최신 버전을 다운로드받아 설치하는 것이다. 최신 기능이 다 들어있어서 좋을 것 같지만, 시중에 나와 있는 대다수의 개발 강의나 오픈소스 프로젝트는 안정적인 LTS 버전을 기준으로 만들어져 있어서 최신 버전과 충돌을 일으키기 십상이다.
또한, NVM을 설치한 후 터미널 창을 닫았다가 다시 켜지 않으면 명령어 인식이 제대로 되지 않아 당황하는 경우가 많다. 새로운 환경 변수나 도구를 세팅했을 때는 항상 터미널을 재시작하는 것을 원칙으로 삼아야 한다. 처음에는 버전 관리 도구가 하나 더 늘어난 것처럼 느껴지겠지만, 프론트엔드 개발 규모가 커질수록 이 도구가 우리의 개발 수명을 연장해 준다는 것을 체감하게 될 것이다.
핵심 요약:
Node.js와 npm 버전 충돌은 프로젝트별 요구 사양이 다를 때 발생하며, 전역 설치만 고집하면 해결하기 어렵다.
NVM(Node Version Manager)을 설치하면 명령어 한 줄로 노드 버전을 자유롭게 전환하여 충돌을 원천 차단할 수 있다.
프로젝트를 시작할 때는 반드시
package.json을 확인하고npm install로 로컬 의존성을 정확하게 세팅해야 한다.
다음 편 예고: 다음 편에서는 리액트(React) 프로젝트 생성 시 자주 나타나는 npx create-react-app 오류 대처법을 알아본다.
0 댓글