node.js 및 npm 설치

본격적으로 Next.js 개발을 시작하기에 앞서, 가장 먼저 해야 할 일은 개발 환경을 구축하는 것입니다.

Next.js는 Node.js 런타임 환경 위에서 동작하며, 프로젝트 관리를 위해 npm(Node Package Manager) 또는 Yarn과 같은 패키지 매니저를 사용합니다.

따라서, 이 두 가지 도구를 여러분의 시스템에 설치하는 것이 첫걸음입니다.

이 절에서는 공식 설치 관리자를 사용하는 방법을 설명합니다. 이미 설치했다면 프로젝트 요구 버전과 맞는지 먼저 확인합니다.

Next.js 16의 최소 Node.js 버전은 20.9입니다. 이 최소값과 현재 지원되는 LTS 여부를 함께 확인해 설치 버전을 고릅니다. 공식 설치 요구사항

Node.js와 npm이란 무엇인가요?

Node.js: 웹 브라우저 밖에서 JavaScript 코드를 실행할 수 있도록 하는 런타임 환경입니다. Next.js는 서버 사이드 렌더링(SSR)이나 Route Handler 같은 서버 기능에 기본적으로 Node.js 런타임을 사용합니다.
npm (Node Package Manager): Node.js 생태계의 표준 패키지 매니저입니다. npm을 사용하면 Next.js 프로젝트에 필요한 다양한 라이브러리(패키지)를 쉽게 설치하고 관리할 수 있습니다. 이 절에서 사용하는 공식 Node.js 설치 관리자에는 npm이 함께 포함됩니다.

처음 한 버전으로 실습한다면 공식 설치 관리자(Installer)를 사용할 수 있습니다. 여러 프로젝트의 버전을 바꿔야 한다면 뒤에서 소개하는 버전 관리 도구도 선택할 수 있습니다.

Node.js 공식 웹사이트 방문 먼저 웹 브라우저를 열고 Node.js 공식 웹사이트(https://nodejs.org/ko)에 접속합니다.

대부분의 사용자에게는 LTS (Long Term Support) 버전을 다운로드하는 것이 권장됩니다.

LTS 버전은 장기적인 지원을 약속하며 안정성이 검증된 버전입니다.

최신 기능이 필요하다면 Current 버전을 선택할 수도 있지만, 안정성을 위해 LTS 버전을 우선적으로 고려하는 것이 좋습니다.

설치 관리자 실행 다운로드한 파일을 실행하고, 화면의 지시에 따라 설치를 진행합니다.

대부분의 경우 특별한 설정을 변경할 필요 없이 Next 버튼을 클릭하여 기본 옵션으로 설치를 완료할 수 있습니다.

설치 과정에서 npm package manager 옵션이 체크되어 있는지 확인하세요. (일반적으로 기본으로 체크되어 있습니다.)

Windows 사용자: .msi 파일을 다운로드하여 실행합니다.
macOS 사용자: .pkg 파일을 다운로드하여 실행합니다.
Linux 사용자: 공식 웹사이트의 가이드를 참조하거나, 배포판의 패키지 관리자를 이용할 수 있습니다. (예: sudo apt install nodejs npm for Ubuntu)

설치가 완료되었다면, 터미널(Windows의 경우 명령 프롬프트 또는 PowerShell, macOS/Linux의 경우 터미널 앱)을 열어 Node.js와 npm이 제대로 설치되었는지 확인합니다.

Node.js 버전 확인 터미널에 다음 명령어를 입력하고 Enter 키를 누릅니다.

node -v

명령어를 실행하면 vXX.XX.X와 같이 설치된 Node.js의 버전이 출력될 것입니다.

예를 들어 v20.11.1은 출력 형식을 보여 주는 예시입니다. 이 번호를 새 설치의 권장 버전으로 고정하지 않습니다.

npm 버전 확인 이어서 npm의 버전도 확인해 보세요.

npm -v

마찬가지로 X.X.X와 같은 형식으로 npm 버전이 출력될 것입니다.

npm 최신 버전 유지 (선택 사항)

npm은 Node.js와 함께 설치되지만, npm 자체도 독립적으로 업데이트될 수 있습니다.

npm을 별도로 갱신할 때는 사용할 npm 버전의 Node.js 요구사항과 프로젝트의 패키지 매니저 기준을 먼저 확인합니다. 최신 npm이 현재 설치한 Node.js에서 항상 동작하는 것은 아닙니다.

다음은 그 조건을 확인한 뒤 선택적으로 최신 npm을 설치하는 명령입니다.

npm install -g npm@latest

-g 옵션은 npm을 전역(global)으로 설치하여 어떤 프로젝트에서도 사용할 수 있도록 합니다.

여러 버전의 Node.js를 사용해야 하는 경우가 발생할 수 있습니다.

예를 들어 어떤 프로젝트는 특정 Node.js 버전을 요구하고, 또 다른 프로젝트는 최신 버전을 사용해야 할 때가 있습니다.

이런 경우 NVM(Node Version Manager)을 사용하면 Node.js 버전을 편리하게 전환할 수 있습니다.

macOS/Linux의 nvm과 Windows의 nvm-windows는 별도 도구입니다. 운영체제에 맞는 설치 방법은 npm 공식 설치 안내에서 확인할 수 있습니다.

설치 실패 신호와 먼저 확인할 위치
실패 신호	먼저 확인	확인으로 알 수 있는 범위
node를 찾지 못함	새 터미널에서 설치 경로와 PATH 확인	명령 탐색 문제인지부터 구분; 재설치를 바로 단정하지 않음
npm만 실패	npm -v와 오류 문구; 설치 시 npm 포함 여부	PATH·설치 누락·셸 정책 등은 오류별로 구분
패키지 설치 실패	오류 코드, registry·프록시·권한 설정	node -v 성공만으로 다운로드나 쓰기 권한을 확인한 것은 아님
버전 요구 불일치	프로젝트와 도구의 engines, 현재 Node/npm 버전	현재 지원 LTS 중 요구 범위에 맞는 버전 선택

node를 찾지 못함: 먼저 확인: 새 터미널에서 설치 경로와 PATH 확인
확인으로 알 수 있는 범위: 명령 탐색 문제인지부터 구분; 재설치를 바로 단정하지 않음
npm만 실패: 먼저 확인: npm -v와 오류 문구; 설치 시 npm 포함 여부
확인으로 알 수 있는 범위: PATH·설치 누락·셸 정책 등은 오류별로 구분
패키지 설치 실패: 먼저 확인: 오류 코드, registry·프록시·권한 설정
확인으로 알 수 있는 범위: node -v 성공만으로 다운로드나 쓰기 권한을 확인한 것은 아님
버전 요구 불일치: 먼저 확인: 프로젝트와 도구의 engines, 현재 Node/npm 버전
확인으로 알 수 있는 범위: 현재 지원 LTS 중 요구 범위에 맞는 버전 선택

버전 출력은 명령이 실행된다는 확인입니다. 프로젝트 설치·개발 서버 실행의 성공 여부는 각 단계에서 따로 확인합니다.