Node.js 설치 방법과 npm 오류 해결: 윈도우·맥 입문 가이드

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

Node.js는 브라우저 밖에서 JavaScript를 실행하는 환경이고, npm은 프로젝트에 필요한 패키지를 설치하고 관리하는 도구입니다. 웹 개발 도구나 JavaScript 프로젝트를 실행할 때 함께 사용하는 경우가 많습니다. 설치 방법과 버전 확인, 주요 npm 오류를 차례로 살펴보겠습니다.

Node.js와 npm, 왜 설치하라고 할까

Node.js는 자바스크립트를 내 컴퓨터에서 돌리는 실행기입니다.

브라우저 안에서만 돌던 자바스크립트를 밖에서도 돌려주는 덕분에 AI 툴이 만든 웹 프로젝트를 내 컴퓨터에 띄워볼 수 있습니다.

npm은 남이 만든 부품을 받아오는 도구라고 보면 됩니다.

npm install을 치면 프로젝트에 필요한 라이브러리가 한꺼번에 내려옵니다. npm은 Node.js를 설치할 때 함께 깔립니다.

LTS와 Current 버전의 차이

LTS는 장기 지원을 받는 릴리스이고 Current는 새 기능이 먼저 반영되는 릴리스입니다. 처음 시작하는 프로젝트에서는 LTS를 검토할 수 있고, 기존 프로젝트에서는 문서나 설정 파일에 지정된 버전이 기준이 됩니다. 현재 지원되는 버전은 공식 다운로드 화면에서 확인할 수 있습니다.

macOS와 Windows의 인스톨러 설치 방법

맥은 .pkg 파일을 받아 안내대로 넘기면 됩니다.

공식 다운로드 페이지에서 시스템에 맞는 macOS 인스톨러를 받아 설치 안내를 따릅니다.

윈도우는 .msi 파일로 설치한 뒤 창을 새로 엽니다.

PATH 항목은 기본값 그대로 두세요. 설치가 끝난 뒤 PowerShell을 새로 열어야 경로가 반영됩니다.

여러 버전을 오갈 일이 있다면 버전 관리자를 씁니다.

nvm이나 fnm 같은 버전 관리자로 프로젝트마다 Node.js 버전을 바꿔 쓸 수 있습니다. npm 공식 문서도 권한 문제를 피하는 가장 좋은 방법으로 이쪽을 꼽습니다. nvm은 맥·리눅스용이라 윈도우는 fnm이나 nvm-windows를 씁니다.

설치 후 새 터미널에서 확인합니다.

node -v
npm -v

각 명령에서 설치한 Node.js와 npm의 버전 번호가 출력되면 터미널에서 실행 파일을 찾을 수 있는 상태입니다.

npm 오류 해결, 자주 만나는 네 가지

'command not found'는 컴퓨터가 설치 위치를 모른다는 뜻입니다.

터미널을 새로 열고 설치 완료 여부와 PATH에 실행 파일 경로가 포함됐는지 확인합니다. 윈도우 PowerShell에서 npm.ps1을 로드할 수 없다고 뜨는 건 실행 정책 탓이니, 같은 명령을 CMD에서 실행하면 됩니다.

EACCES: 설치 폴더의 접근 권한

npm install -g에서 EACCES permission denied가 나왔다면 전역 설치 폴더에 쓸 권한이 없다는 뜻입니다. 관리자 권한으로 실행하는 것이 모든 권한 오류의 해결책은 아니며, 설치 위치와 현재 계정의 권한에 따라 조치가 달라집니다. npm 공식 문서가 권하는 첫 번째 해법은 버전 관리자로 Node.js를 다시 설치하는 것입니다. 직접 고치려면 npm config set prefix ~/.local로 전역 설치 위치를 옮기고 PATH에 ~/.local/bin을 추가합니다.

ERESOLVE는 부품끼리 버전이 맞지 않는다는 신호입니다.

ERESOLVE unable to resolve dependency tree는 라이브러리가 요구하는 짝(peer dependency) 버전과 프로젝트에 깔린 버전이 다를 때 납니다. 메시지에 적힌 패키지와 요구 버전을 읽고 버전을 맞추는 게 정석입니다. --legacy-peer-deps는 peer dependency를 아예 무시하는 옵션이라(공식 문서 설명) 임시방편에 그칩니다.

버전 불일치는 프로젝트가 원하는 Node.js 버전부터 확인합니다.

EBADENGINE 경고가 보이면 package.json의 engines 항목이나 .nvmrc 파일을 열어보세요. 적힌 버전과 node -v 결과가 다르다면 버전 관리자로 맞춰주면 됩니다.

세부 설정과 지원 범위는 Node.js 공식 다운로드를 참고해 보세요.

내 컴퓨터의 프로젝트에서 실제 서비스까지

로컬에서 화면이 잘 열리면 다른 사람도 사용할 수 있게 만들어보고 싶어집니다. 배포와 데이터 관리 등 새로 살펴볼 부분도 생기고요.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행하며, 시제품에 필요한 기능을 정리하고 운영할 수 있는 서비스로 이어가는 과정을 돕습니다.

만들어둔 프로젝트를 다음 단계로 옮기고 싶다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)