node.js 및 npm 설치

2장에서는 Next.js로 개발하기 위한 환경을 갖춥니다. Next.js는 Node.js 런타임 위에서 동작하며, 프로젝트를 관리할 때 npm(Node Package Manager)이나 Yarn 같은 패키지 매니저를 씁니다. 그래서 이 두 도구를 시스템에 설치하는 것이 첫걸음입니다. 이 글에서는 공식 설치 관리자를 쓰는 방법을 설명하며, 이미 설치했다면 프로젝트가 요구하는 버전과 맞는지부터 확인합니다.

Next.js 16이 요구하는 Node.js의 최소 버전은 20.9입니다. 이 최솟값과 함께 지금 지원되는 LTS인지도 확인해 설치할 버전을 고릅니다(Next.js 문서의 시스템 요구사항). 14장의 테스트 도구와 15장의 Netlify CLI처럼 뒤의 장에서 설치하는 도구 가운데는 Node.js 22 이상을 요구하는 것도 있으므로, 처음부터 지금 지원 중인 LTS를 설치해 두면 장마다 Node.js를 다시 올리지 않아도 됩니다.

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

Node.js는 웹 브라우저 밖에서 JavaScript 코드를 실행할 수 있게 하는 런타임 환경입니다. Next.js는 서버 측 렌더링(SSR)이나 Route Handler 같은 서버 기능에 기본으로 Node.js 런타임을 씁니다.

npm은 Node.js 생태계의 표준 패키지 매니저로, Next.js 프로젝트에 필요한 여러 라이브러리(패키지)를 쉽게 설치하고 관리하게 해 줍니다. 이 글에서 쓰는 공식 Node.js 설치 관리자에는 npm이 함께 들어 있습니다.

Node.js와 npm 설치하기

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

먼저 웹 브라우저로 Node.js 공식 웹사이트에 들어갑니다. 대부분의 사용자에게는 LTS(Long Term Support) 버전을 권합니다. LTS 버전은 오랫동안 지원되며 안정성이 검증된 버전입니다. 새 메이저 버전은 LTS가 되기 전에 Current 단계를 거치고, Node.js 27부터는 그 앞에 Alpha 단계가 더해졌습니다. 2026년 11월 현재 다운로드 페이지에서 고를 수 있는 지원 버전은 LTS 버전들과 v27 Alpha이며, Node.js는 운영 환경에 LTS만 쓰라고 안내하므로 이 교재의 실습에도 LTS를 고릅니다.

다음으로 내려받은 설치 파일을 실행하고 화면의 안내에 따라 설치합니다. 대부분은 설정을 바꿀 필요 없이 Next 버튼을 눌러 기본 옵션으로 설치를 마칠 수 있으며, 설치하는 동안 npm package manager 옵션이 체크되어 있는지 확인하세요(보통 기본으로 체크되어 있습니다). Windows에서는 .msi 파일을, macOS에서는 .pkg 파일을 내려받아 실행합니다. Linux에서는 공식 웹사이트의 안내를 따르거나 배포판의 패키지 관리자를 쓸 수 있는데, 예를 들어 Ubuntu의 sudo apt install nodejs npm처럼 배포판이 제공하는 패키지는 버전이 Next.js 16의 요구보다 낮을 수 있으므로 설치한 뒤 버전을 꼭 확인합니다.

설치 확인과 버전 업데이트

설치를 마쳤다면 터미널(Windows라면 명령 프롬프트나 PowerShell, macOS와 Linux라면 터미널 앱)을 새로 열어 Node.js와 npm이 제대로 설치되었는지 확인합니다. 먼저 다음 명령으로 Node.js의 버전을 확인합니다.

node -v

명령을 실행하면 vXX.XX.X 같은 형식으로 설치된 Node.js의 버전이 나옵니다. 예를 들어 v20.11.1은 출력의 형식을 보여 주는 예일 뿐이며, 이 번호를 새로 설치할 권장 버전으로 정하지 않습니다. 이어서 npm의 버전도 확인합니다.

npm -v

마찬가지로 X.X.X 형식으로 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.js와 npm 설치에서 확인할 수 있습니다.

설치 후 문제가 생겼을 때

위 그림은 실패한 단계부터 확인하는 방법을 보여 줍니다. 그림의 요약처럼 Node의 버전 출력과 패키지 설치, 개발 서버의 실행은 서로 다른 확인이므로, 오류 문구에 맞는 위치부터 좁혀 갑니다. 실행한 명령과 오류, 현재 버전과 요구 범위라는 첫 실패의 단서에서 네 가지 점검으로 갈라지며, 그림의 캡션이 밝히듯 이 화살표는 오류가 난 단계에 맞는 첫 점검을 고르는 분기일 뿐 네 점검을 모두 차례로 실행하라는 뜻이 아닙니다. 버전 출력이 성공했다고 다운로드나 프로젝트의 요구 범위까지 확인된 것도 아닙니다.

그림 아래의 네 칸은 분기마다 먼저 볼 곳을 정리합니다. node를 찾지 못하면 새 터미널의 설치 경로와 PATH(터미널이 명령 이름으로 실행 파일을 찾을 때 차례로 살펴보는 폴더 목록을 담은 환경 변수)부터 확인해 명령 탐색의 문제를 가려내며, 이 신호만으로 재설치가 필요하다고 단정하지 않습니다. npm만 실패하면 npm -v의 오류와 설치할 때 npm이 포함되었는지를 보고, PATH나 설치 누락, PowerShell 실행 정책 가운데 무엇인지 실제 오류로 구분합니다. 패키지 설치가 실패하면 오류 코드와 registry(npm이 패키지를 내려받는 저장소 서버로, 기본값은 https://registry.npmjs.org), 프록시, 쓰기 권한을 보며, node -v의 성공만으로 다운로드와 설치 권한을 확인한 것은 아닙니다. 요구 버전이 맞지 않으면 프로젝트와 도구의 engines(package.json에 그 패키지가 동작하는 Node.js와 npm의 버전 범위를 적는 항목), 현재의 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을 다시 확인합니다.

정리

• Next.js는 Node.js 런타임 위에서 동작하고, npm 같은 패키지 매니저로 프로젝트의 패키지를 관리합니다.
• Next.js 16은 Node.js 20.9 이상을 요구하며, 설치할 때는 이 최솟값과 함께 지금 지원되는 LTS인지 확인합니다.
• 설치한 뒤에는 새 터미널에서 node -v와 npm -v로 두 도구를 따로 확인합니다.
• 여러 Node.js 버전이 필요하면 NVM 같은 버전 관리 도구를 쓰며, macOS·Linux와 Windows의 도구는 서로 다릅니다.
• 문제가 생기면 첫 오류가 난 단계부터 확인하고, 버전 출력의 성공을 설치나 다운로드의 성공으로 보지 않습니다.

연습 문제

1. 버전은 나오는데 다운로드가 실패할 때

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

2. 배포판 패키지로 설치한 Node

Ubuntu에서 sudo apt install nodejs npm으로 설치한 뒤 node -v가 v18.19.1을 출력했습니다. Next.js 16 프로젝트를 만들 수 있을까요?

3. 최신 npm으로 올리기 전에

npm install -g npm@latest를 실행하기 전에 확인해야 할 것은 무엇일까요?

다음 글 Next.js 16 프로젝트 생성에서는 create-next-app으로 새 프로젝트를 만들고 교재에서 쓸 설정을 고릅니다.