node.js 및 npm 설치

Next.js 실행에 필요한 Node.js와 npm의 역할을 이해하고 운영체제별 설치·버전 확인·NVM 관리까지 진행합니다.

본격적으로 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이 함께 포함됩니다.

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 버전 관리 (선택 사항: NVM)

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

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

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

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

실패한 단계부터 확인합니다

Node 버전 출력, 패키지 설치, 개발 서버 실행은 서로 다른 확인입니다. 오류 문구에 맞는 위치부터 좁힙니다.

node를 찾지 못함

먼저 확인: 새 터미널의 설치 경로와 PATH.

명령 탐색 문제부터 구분합니다. 이 신호만으로 재설치가 필요하다고 단정하지 않습니다.

npm만 실패

먼저 확인: npm -v의 오류와 설치 시 npm 포함 여부.

PATH·설치 누락·PowerShell 정책은 실제 오류에 따라 구분합니다.

패키지 설치 실패

먼저 확인: 오류 코드, registry·프록시·쓰기 권한.

node -v 성공만으로 다운로드·설치 권한을 확인한 것은 아닙니다.

버전 요구 불일치

먼저 확인: 프로젝트·도구의 engines와 현재 Node/npm 버전.

현재 지원되는 LTS 중 요구 범위에 맞는 버전을 선택합니다. 최소 버전과 지원 상태는 별개입니다.

Next.js 16의 Node 최소 버전은 20.9입니다. 이 번호를 현재 권장 LTS로 고정하지 않으며, npm 별도 갱신도 해당 npm의 Node 요구사항을 먼저 확인합니다.

예시

node -v가 v18.20.8을 출력하면 명령 탐색과 실행은 성공한 것입니다. 하지만 Next.js 16의 최소 요구인 20.9에는 못 미칩니다. 출력이 나온다는 확인에서 끝내지 않고 설치 버전 → 프로젝트 요구 범위 → 현재 지원 상태 순서로 확인합니다. 요구 범위에 맞는 Node를 선택한 뒤 새 터미널에서 Node와 npm을 다시 확인합니다.

독립 확인

새 터미널에서 Node와 npm의 버전 출력이 모두 성공했지만 프로젝트 생성 도중 패키지 다운로드가 실패했습니다. Node를 바로 재설치해야 하는지, 이미 확인한 사실과 다음에 확인할 사실을 나누어 설명하세요.

판단 과정 확인

두 버전 출력은 명령을 찾고 실행할 수 있다는 증거입니다. registry에 접속하거나 설치 폴더에 파일을 쓸 수 있다는 증거는 아닙니다. 생성 명령의 첫 오류에서 다운로드·프록시·권한 중 어느 단계가 실패했는지 확인하고 해당 조건을 해결합니다. 이 결과만으로 Node 재설치를 원인에 맞는 조치라고 결정할 수 없습니다.