개발 준비 운동 — Node.js, 에디터, 터미널, 그리고 첫 실행

2026-04-13Views 107약 8분

시동이 잘 걸려야 공부도 재밌다

새로운 기술을 배울 때 가장 먼저 부딪히는 벽은 의외로 문법이 아닙니다. 설치입니다. 화면에는 영어가 잔뜩 뜨고, 터미널은 깜빡거리고, localhost는 열리지 않고, 갑자기 자신감은 사라집니다. 마치 운동하러 갔는데 운동화 끈이 안 묶여 있는 기분이죠.

이번 장의 목표는 단순합니다. 최신 Next.js를 무리 없이 시작할 수 있는 개발 환경을 준비하는 것입니다. 오늘 여기서 해둘 일은 네 가지입니다.

Node.js를 설치하고 버전을 확인한다.
코드를 작성할 에디터를 준비한다.
터미널의 가장 기본적인 사용법을 익힌다.
Next.js 앱이 내 컴퓨터에서 실제로 실행되는지 확인한다.

여기까지 끝내면, 다음 장부터는 진짜로 손을 움직이며 프로젝트를 만들어 갈 수 있습니다. 우리가 앞으로 만들 앱은 '작은 기록 상점'이고, 오늘은 그 여정을 시작하기 위한 준비 운동이라고 생각하면 됩니다.

개발 준비 운동 — Node.js, 에디터, 터미널, 그리고 첫 실행

Node.js 설치하기

Next.js는 혼자서는 돌아가지 않습니다. 그 아래에서 JavaScript를 실행해 주는 Node.js가 필요합니다. Node.js는 브라우저 밖에서도 자바스크립트를 실행할 수 있게 해 주는 환경이고, npm은 필요한 도구와 라이브러리를 설치하는 꾸러미 관리자라고 생각하면 됩니다.

가장 쉬운 방법은 공식 사이트에서 설치 파일을 받는 것입니다.³

Node.js 공식 사이트에 접속합니다.
LTS 버전을 다운로드합니다.
설치 프로그램을 기본 옵션으로 진행합니다.
설치가 끝나면 터미널을 새로 엽니다.

설치가 끝났다면, 정말 잘 설치되었는지 확인해 봅시다.

node -v
npm -v

여기서 node -v 결과가 20.9 이상이면 최신 Next.js를 시작할 준비가 된 것입니다.² 숫자가 나온다면 성공입니다. 숫자가 아니라 에러가 나온다면, 아직 설치가 제대로 되지 않았거나 터미널이 이전 상태를 기억하고 있을 가능성이 큽니다. 이럴 때는 터미널을 완전히 닫고 다시 열어 보는 것만으로도 해결되는 경우가 많습니다.

한마디로 정리하면 이렇습니다.

Node.js는 엔진이고, npm은 공구함입니다. 엔진이 없으면 차는 안 움직이고, 공구함이 없으면 부품을 못 붙입니다.

어떤 에디터를 쓰면 좋을까

에디터는 말 그대로 코드를 쓰는 작업대입니다. 무엇을 써도 되지만, 초보자라면 Visual Studio Code를 가장 무난하게 추천할 수 있습니다. 많이 쓰이고, 자료가 많고, Next.js와 궁합도 좋기 때문입니다.

특히 Next.js는 TypeScript 플러그인과 타입 검사 기능을 제공해서, VS Code 같은 편집기에서 자동완성이나 오류 표시를 더 잘 해 줍니다. 공식 문서에서는 VS Code에서 TypeScript: Select TypeScript Version 명령으로 Use Workspace Version을 선택하는 방법도 안내합니다.²

처음에는 에디터에 너무 많은 확장을 깔 필요는 없습니다. 오히려 너무 많이 깔면 뭐가 뭔지 더 헷갈릴 수 있습니다. 처음엔 딱 이 정도면 충분합니다.

VS Code
ESLint 확장
Tailwind CSS IntelliSense 확장

물론 없어도 시작은 됩니다. 하지만 있으면 "왜 밑줄이 떴지?" 같은 순간을 조금 빨리 이해할 수 있습니다.

터미널, 너무 무서워하지 말자

터미널은 검은 창처럼 보여서 괜히 긴장되지만, 사실은 컴퓨터에게 글로 부탁하는 창입니다. 마우스로 클릭하던 일을 키보드로 말하는 셈이죠.

처음엔 이 정도만 알면 충분합니다.

하고 싶은 일	macOS / Linux	Windows PowerShell
현재 위치 보기	`pwd`	`pwd`
폴더 안 목록 보기	`ls`	`ls` 또는 `dir`
폴더 이동하기	`cd 폴더이름`	`cd 폴더이름`
한 단계 위로 가기	`cd ..`	`cd ..`
실행 중인 서버 끄기	`Ctrl + C`	`Ctrl + C`

예를 들어 cd my-app은 "my-app 폴더로 들어가자"라는 뜻입니다. npm run dev는 "개발 서버를 실행하자"라는 뜻이고요.

처음에는 명령어를 외우려 하지 말고, 무슨 뜻인지 느낌을 잡는 것이 더 중요합니다. cd는 들어가기, ls는 보여주기, Ctrl + C는 멈추기. 이 정도만 익혀도 충분히 앞으로 갈 수 있습니다.

작업 폴더를 먼저 정리하자

프로젝트는 아무 데나 만들 수 있지만, 초보자일수록 작업용 폴더를 하나 따로 만드는 습관이 좋습니다. 예를 들면 이런 식입니다.

mkdir dev
cd dev

그 안에 Next.js 프로젝트들을 차곡차곡 넣으면 나중에 찾기도 쉽습니다. 폴더 이름은 가능하면 영문 소문자와 하이픈(-) 위주로 두는 편이 안전합니다. 어떤 환경에서는 한글 경로나 동기화 폴더가 문제를 일으키는 경우가 있고, Windows에서는 PowerShell 보안 정책 때문에 스크립트 실행 오류가 나는 경우도 있습니다.⁵

겁먹을 필요는 없습니다. 다만 초보자라면 설치 초반에는 변수가 적을수록 좋습니다. 깔끔한 영문 폴더, 단순한 경로, 기본 설정. 이것만으로도 성공 확률이 꽤 올라갑니다.

이제 정말로 첫 실행을 해보자

다음 장에서는 create-next-app의 선택지를 하나씩 뜯어보며 프로젝트를 본격적으로 만들 것입니다. 하지만 오늘은 "내 컴퓨터에서 Next.js가 진짜 켜지는가?"를 확인하는 짧은 실행 테스트만 해보겠습니다.

터미널에서 작업 폴더로 이동한 뒤 아래 명령어를 입력합니다.

npx create-next-app@latest next-smoke-test --yes
cd next-smoke-test
npm run dev

이 명령은 최신 방식으로 테스트용 앱을 빠르게 만들어 줍니다. --yes를 붙이면 기본값으로 진행되는데, 이 기본값에는 TypeScript, Tailwind CSS, ESLint, App Router, Turbopack, @/* import alias 같은 설정이 포함됩니다.²

서버가 잘 실행되면 보통 http://localhost:3000 주소를 열라고 안내합니다. 브라우저에서 그 주소로 들어가 보세요. 기본 Next.js 시작 화면이 보인다면 성공입니다.²

이 순간이 작지만 꽤 중요합니다. 이제 여러분의 컴퓨터는 단순히 "Next.js를 공부할 예정인 컴퓨터"가 아니라, 실제로 Next.js를 실행할 수 있는 개발 머신이 되었습니다.

화면이 바뀌면 더 안심된다

기본 화면이 떴다면, 이제 진짜로 잘 돌아가는지 확인해 보고 싶어집니다. 그럴 땐 홈 페이지 파일을 열어 아주 조금만 바꿔 보세요.

예를 들어 app/page.tsx 또는 src/app/page.tsx에 있는 내용을 단순하게 바꿔도 됩니다.

export default function Page() {
  return <h1>안녕, Next.js!</h1>
}

저장한 뒤 브라우저를 보면 거의 바로 화면이 바뀝니다. 이것을 Hot Module Reloading이라고 생각하면 됩니다. 어려운 말 같지만 뜻은 단순합니다. "수정하면 새로고침을 많이 대신해 준다"입니다.⁴

개발할 때 이 감각이 중요합니다. 고치고, 저장하고, 바로 확인하는 흐름이 자연스러워야 공부도 덜 지칩니다.

개발 서버 명령어는 세 가지만 먼저 기억하자

Next.js를 쓰다 보면 명령어가 많아 보이지만, 초반엔 세 가지만 알면 됩니다.²⁴

npm run dev
npm run build
npm run start

npm run dev는 개발용 서버를 켭니다. 지금 우리가 가장 자주 쓸 명령어입니다.

npm run build는 배포용으로 앱을 정리하고 묶는 과정입니다. 시험공부로 치면 최종 정리본을 만드는 느낌입니다.

npm run start는 그렇게 만들어진 결과물을 실제 서비스처럼 실행합니다.

참고로 최신 Next.js에서는 Turbopack이 기본 번들러로 동작합니다.² 번들러는 여러 파일을 실행하기 좋게 정리해 주는 도구라고 이해하면 됩니다. 이름은 조금 어렵지만, 초보자 입장에서는 "개발 서버가 더 빠르게 반응하도록 돕는 엔진" 정도로 받아들이면 충분합니다.

또 한 가지, Next.js 16부터는 next build가 린터를 자동으로 실행하지 않습니다. 즉, 코드 검사와 빌드는 이제 조금 더 분리해서 생각하는 편이 좋습니다.² 초반에는 "왜 예전 글이랑 다르지?" 싶은 순간이 있을 수 있는데, 이런 변화가 최신 버전 학습에서 자주 생깁니다.

포트가 겹치면 당황하지 말기

가끔 localhost:3000이 이미 다른 프로그램에서 사용 중일 때가 있습니다. 이럴 때는 "내가 뭘 잘못했나?"보다 "아, 자리가 이미 찼구나"라고 생각하면 됩니다.

그럴 때는 포트를 바꿔 실행하면 됩니다.

npm run dev -- --port 3001

여기서 3001은 그냥 다른 방 번호 같은 것입니다. 공식 CLI 문서에서도 next dev와 next start에서 포트를 바꿀 수 있다고 안내합니다.⁴ npm run 뒤에 옵션을 넘길 때 --를 한 번 더 넣는 점만 기억하면 됩니다.⁴

초보자가 자주 막히는 지점

처음 설치할 때는 실력보다 환경이 더 큰 변수입니다. 아래 상황은 정말 자주 만납니다.

`node -v` 또는 `npm -v`가 안 나올 때

대부분은 Node.js 설치가 끝난 뒤 터미널을 다시 열지 않아서 그렇습니다. 터미널을 완전히 닫고 다시 열어 보세요. 그래도 안 되면 Node.js를 다시 설치하는 쪽이 빠를 때가 많습니다.

`npx` 실행이 안 될 때

이 역시 Node.js 설치 문제이거나 터미널 환경 문제인 경우가 많습니다. 먼저 node -v, npm -v부터 확인하세요. 둘 다 정상이어야 npx create-next-app@latest도 자연스럽게 됩니다.

Windows에서 스크립트 실행 권한 오류가 날 때

PowerShell에서 보안 정책 때문에 막히는 경우가 있습니다. 이런 경우 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser로 해결되는 일이 많습니다.⁵ Windows는 이런 한 번의 문지기 테스트를 통과하면 그다음부터는 훨씬 편해집니다.

브라우저에서 페이지가 안 열릴 때

서버가 아직 완전히 뜨지 않았을 수 있습니다. 터미널 메시지를 먼저 확인하세요. localhost:3000 대신 다른 포트로 켜졌을 수도 있습니다. 또는 방화벽, 회사 보안 프로그램, 포트 충돌 같은 외부 원인일 수도 있습니다.

오늘의 목표는 "설치 완료"가 아니라 "실행 성공"이다

개발 환경 준비에서 가장 중요한 것은 화려한 설정이 아닙니다. 실제로 돌아가는 상태입니다. 에디터가 켜지고, 터미널이 열리고, node -v가 나오고, npm run dev가 성공하고, 브라우저에 Next.js 화면이 뜨는 것. 여기까지가 오늘의 승리입니다.

이 승리를 작게 보면 안 됩니다. 초보자에게는 이 단계가 가장 큰 허들일 때가 많기 때문입니다. 하지만 한 번만 통과하면, 그다음부터는 배울 수 있는 것이 눈에 보이기 시작합니다.

다음 장에서는 이제 본격적으로 create-next-app으로 첫 프로젝트를 만들고, 어떤 선택지를 고르면 좋은지 하나씩 살펴보겠습니다. 그리고 우리의 실전 프로젝트, '작은 기록 상점'을 향한 첫 폴더도 제대로 만들어 볼 것입니다.