node.js 및 npm 설치
Next.js 실행에 필요한 Node.js와 npm의 역할을 이해하고 운영체제별 설치·버전 확인·NVM 관리까지 진행합니다.
본격적으로 Next.js 개발을 시작하기에 앞서, 가장 먼저 해야 할 일은 개발 환경을 구축하는 것입니다.
Next.js는 Node.js 런타임 환경 위에서 동작하며, 프로젝트 관리를 위해 npm(Node Package Manager) 또는 Yarn과 같은 패키지 매니저를 사용합니다.
따라서, 이 두 가지 도구를 여러분의 시스템에 설치하는 것이 첫걸음입니다.
이 절에서는 Node.js와 npm을 설치하는 가장 일반적이고 권장되는 방법에 대해 상세히 안내해 드리겠습니다.
이미 설치되어 있다면 버전을 확인하고 최신 상태로 유지하는 방법을 살펴보겠습니다.
먼저 Node.js 설치가 Next.js 실습에서 어떤 책임을 맡는지 한눈에 정리합니다.
설치의 목적은 프로그램을 깔아 두는 것이 아니라 프로젝트 생성, 개발 서버 실행, 패키지 설치가 같은 터미널에서 동작하게 만드는 것이다.
| 준비 요소 | 맡는 역할 | 확인 명령/행동 | 문제가 있으면 |
|---|---|---|---|
| Node.js | 브라우저 밖에서 JavaScript 실행 | node -v | LTS 설치 또는 버전 관리자 확인 |
| npm | 패키지 설치와 script 실행 | npm -v | Node 설치 옵션과 PATH 확인 |
| 터미널 PATH | 명령어를 어디서든 찾게 함 | 새 터미널에서 node/npm 실행 | 터미널 재시작 또는 환경 변수 확인 |
| 패키지 매니저 | npm, yarn, pnpm 중 팀 기준 선택 | 프로젝트 lockfile 확인 | 한 프로젝트에서 하나로 통일 |
| 프로젝트 생성 | Next.js 예제 시작점 생성 | create-next-app 실행 가능 여부 | 권한, 네트워크, npm cache 확인 |
Node.js와 npm이란 무엇인가요?
Node.js와 npm 설치에서는 버전, PATH, 패키지 매니저, 프로젝트 생성 가능 여부를 확인합니다.
다음 표는 Node.js와 npm을 단순 설치 파일이 아니라 런타임, 패키지 관리, 실행 명령의 조합으로 이해하게 도와줍니다.
둘은 함께 설치되는 경우가 많지만 역할은 다르다. 문제를 해결할 때도 런타임 문제인지 패키지 문제인지 구분해야 한다.
| 도구 | 역할 | Next.js에서 쓰이는 곳 | 대표 확인 |
|---|---|---|---|
| Node.js | JavaScript 런타임 | 개발 서버, 빌드, 서버 렌더링 | node -v로 버전 출력 |
| npm | 패키지 매니저와 script runner | npm install, npm run dev/build | npm -v와 package.json scripts |
| package.json | 프로젝트 의존성과 명령 목록 | next dev, next build 명령 정의 | scripts와 dependencies 확인 |
| lockfile | 설치되는 패키지 버전 고정 | 팀원 간 동일한 의존성 재현 | package-lock.json 등 하나만 유지 |
| npx/npm exec | 패키지 명령을 일회성 실행 | create-next-app 실행 | 명령 실행 후 프로젝트 폴더 생성 |
- 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 설치하기
Node.js를 설치하는 가장 쉽고 권장되는 방법은 공식 웹사이트에서 제공하는 설치 관리자(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 npmfor 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은 Node.js와 함께 설치되지만, npm 자체도 독립적으로 업데이트될 수 있습니다.
때때로 최신 버전의 npm이 더 나은 성능이나 새로운 기능을 제공하므로, npm을 최신 상태로 유지하는 것이 좋습니다.
다음 명령어를 사용하여 npm을 최신 버전으로 업데이트할 수 있습니다.
npm install -g npm@latest-g 옵션은 npm을 전역(global)으로 설치하여 어떤 프로젝트에서도 사용할 수 있도록 합니다.
Node.js 버전 관리 (선택 사항: NVM)
여러 버전의 Node.js를 사용해야 하는 경우가 발생할 수 있습니다.
예를 들어 어떤 프로젝트는 특정 Node.js 버전을 요구하고, 또 다른 프로젝트는 최신 버전을 사용해야 할 때가 있습니다.
이런 경우 NVM(Node Version Manager)을 사용하면 Node.js 버전을 편리하게 전환할 수 있습니다.
NVM 설치와 상세 사용법은 이 책의 범위를 약간 벗어나지만, 필요하다면 검색 엔진에서 NVM 설치를 검색해 별도로 학습해 보시길 권장합니다.
Node.js와 npm 설치는 단순히 설치 파일을 실행하는 것으로 끝나지 않습니다.
LTS 선택, 터미널 재시작, 버전 확인, 필요 시 버전 관리자 도입까지 한 번에 점검하면 이후 프로젝트 생성 단계에서 막히는 일을 줄일 수 있습니다.
설치 후에는 버전 출력, PATH 반영, 프로젝트 생성 가능 여부를 순서대로 확인합니다.
설치 관리자가 끝났다고 개발 환경이 준비된 것은 아니다. 새 터미널에서 실제 명령이 동작하는지 확인해야 한다.
| 순서 | 확인할 것 | 좋은 결과 | 안 되면 볼 곳 |
|---|---|---|---|
| 1 | 새 터미널 열기 | 이전 설치 상태가 반영됨 | 터미널 완전 종료 후 재실행 |
| 2 | node -v | 버전 번호가 출력됨 | PATH, 설치 위치, 버전 관리자 |
| 3 | npm -v | npm 버전이 출력됨 | Node 설치 옵션, npm 포함 여부 |
| 4 | 프로젝트 생성 명령 | 새 Next.js 폴더가 생성됨 | 네트워크, 권한, npm cache |
| 5 | 개발 서버 실행 | localhost 주소가 열림 | 포트 충돌, 의존성 설치, 로그 |
설치 후 문제가 생기면 증상별로 확인 위치를 좁혀 가는 편이 빠릅니다.
무작정 재설치하기 전에 어떤 단계에서 실패했는지 나누면 해결 시간이 줄어든다.
| 증상 | 가능한 원인 | 먼저 확인 | 다음 조치 |
|---|---|---|---|
| node 명령을 찾지 못함 | PATH 미반영 또는 설치 실패 | 새 터미널, 설치 경로 | 재시작 후 LTS 재설치 |
| npm 명령만 실패 | npm 옵션 누락 또는 npm 손상 | Node 설치 옵션, npm -v | Node 재설치 또는 npm 복구 |
| 패키지 설치가 느리거나 실패 | 네트워크, 프록시, registry 문제 | 인터넷, 회사망, registry 설정 | 네트워크 변경 또는 cache 정리 |
| 권한 오류 발생 | 전역 설치 권한 또는 폴더 권한 | 사용자 폴더, 관리자 권한 여부 | 전역 설치 줄이고 프로젝트 로컬 사용 |
| 프로젝트마다 버전이 다름 | Node 버전 요구사항 차이 | package.json engines, 문서 요구사항 | 버전 관리자 도입 검토 |
프로젝트를 만들기 전에는 버전, 패키지 매니저, 터미널, 권한 상태가 안정적인지 확인합니다.
환경이 흔들리면 Next.js 코드 문제가 아닌데도 예제가 실패한다. 시작 전에 환경 변수를 줄인다.
| 안정화 항목 | 확인 기준 | 좋은 상태 | 기록할 것 |
|---|---|---|---|
| Node 버전 | LTS 계열 사용 | 팀/교재 기준과 맞음 | node -v 결과 |
| npm 버전 | 명령 실행 가능 | install, run script가 동작 | npm -v 결과 |
| 패키지 매니저 | npm/yarn/pnpm 중 하나 | lockfile이 하나만 생김 | 사용할 명령 세트 |
| 터미널 | 프로젝트 폴더에서 실행 | 경로와 권한이 명확함 | 작업 폴더 위치 |
| 개발 서버 | localhost 접속 | 포트 충돌 없이 화면 열림 | 실행 명령과 URL |
Node.js와 npm 설치가 완료되면 Next.js 개발 환경의 기본 요구사항을 충족합니다.
이 다이어그램은 Node.js와 npm 설치를 Next.js 개발 환경 준비 흐름으로 정리합니다.
설치 확인이 끝나야 다음 절의 프로젝트 생성 명령이 의미를 갖는다. 각 단계의 성공 신호를 확인한다.
| 단계 | 하는 일 | 성공 신호 | 다음 단계 |
|---|---|---|---|
| 1. 설치 | Node.js LTS 설치 | node/npm 명령이 출력됨 | 버전 확인 |
| 2. 확인 | node -v, npm -v 실행 | 버전 번호 확인 | 패키지 매니저 기준 선택 |
| 3. 생성 | create-next-app 실행 | 프로젝트 폴더 생성 | 의존성 설치 확인 |
| 4. 실행 | 개발 서버 실행 | localhost 페이지 표시 | 첫 페이지 수정 |
| 5. 기록 | 버전과 명령을 메모 | 다시 재현 가능 | 팀/개인 환경 표준화 |
마지막으로 Node.js, npm, 선택적 버전 관리 도구가 실습 안정성에 어떻게 연결되는지 점검합니다.
버전이 바뀌면 설치 결과와 빌드 결과가 달라질 수 있다. 프로젝트마다 요구 버전을 확인하는 습관이 필요하다.
| 관리 대상 | 언제 신경 쓰나 | 확인할 것 | 안정화 행동 |
|---|---|---|---|
| Node.js 버전 | 프로젝트 생성 전, 빌드 오류 발생 시 | node -v, engines | LTS 기준으로 맞춤 |
| npm 버전 | install 결과가 다를 때 | npm -v, lockfile 변화 | 팀 기준 명령 사용 |
| 버전 관리자 | 여러 프로젝트를 오갈 때 | 프로젝트별 Node 요구사항 | 프로젝트 진입 시 버전 전환 |
| 전역 패키지 | 내 PC에서만 되는 명령이 있을 때 | global install 의존 여부 | 가능하면 프로젝트 script로 실행 |
| 문제 기록 | 설치 오류를 반복할 때 | 오류 메시지, 버전, OS, 명령 | 해결 절차를 짧게 남김 |