HTML 파일은 열면 되는데 웹앱은 왜 실행해야 하나요?

처음 만든 index.html 파일은 더블클릭만 해도 브라우저에서 열립니다. 그런데 Next.js로 프로젝트를 만들고 나면 파일을 클릭해도 웹페이지가 열리지 않아요.

대신 AI가 이런 말을 합니다.

개발 서버를 실행하겠습니다.
npm run dev
http://localhost:3000에서 확인하세요.

페이지 하나를 보려는데 왜 서버를 실행해야 할까요? localhost는 무엇이고, 뒤에 붙은 3000은 왜 필요한 걸까요?

두 페이지는 브라우저에서 비슷하게 보여도 만들어지고 전달되는 방식이 다릅니다.

HTML 파일은 브라우저가 바로 읽을 수 있어요

HTML은 웹페이지의 내용을 적는 문서 형식입니다. index.html 파일 안에는 제목, 문단, 버튼처럼 화면에 보여줄 구조가 들어 있어요.

<h1>Hello world</h1>
<p>첫 번째 웹페이지입니다.</p>

브라우저는 HTML 문서를 읽을 수 있는 프로그램입니다. .docx 파일을 Word로 여는 것처럼 .html 파일을 브라우저로 열 수 있어요.

index.html
→ 브라우저가 파일을 직접 읽음
→ 화면에 표시

파일을 더블클릭했을 때 주소창을 보면 다음처럼 내 컴퓨터의 파일 위치가 나타날 수 있습니다.

file:///Users/me/project/index.html

인터넷의 웹사이트에 접속한 것이 아닙니다. 브라우저가 내 컴퓨터에 저장된 파일 하나를 직접 연 거예요.

이런 페이지를 정적 페이지라고 해요

미리 작성된 파일을 브라우저가 그대로 보여주는 페이지를 정적 페이지라고 합니다.

여기서 “정적”이라는 말이 아무 움직임도 없다는 뜻은 아닙니다. CSS로 애니메이션을 넣거나 JavaScript로 버튼을 작동하게 할 수도 있어요.

핵심은 사용자가 페이지를 열 때마다 서버가 새로운 결과를 만들지 않고, 준비된 파일을 전달한다는 점입니다.

미리 만들어둔 HTML
→ 누구에게나 같은 파일을 보여줌

회사 소개, 행사 안내, 간단한 포트폴리오처럼 내용을 보여주는 것이 중심인 페이지는 정적 파일만으로도 만들 수 있습니다.

웹앱은 파일 하나가 아니에요

신청 폼, 관리자 페이지, 로그인, 결제처럼 기능이 있는 웹 애플리케이션은 보통 여러 부분이 함께 작동합니다.

화면
+ 사용자 입력 처리
+ 페이지 이동
+ 서버 기능
+ 데이터베이스 연결
+ 로그인과 권한 확인

Next.js 프로젝트를 열어보면 HTML 파일 하나가 아니라 여러 폴더와 코드 파일이 있습니다. 이 파일들은 사람이 기능을 만들고 관리하기 좋은 형태로 나뉘어 있어요.

하지만 브라우저가 이 프로젝트의 모든 소스 코드를 그대로 읽고 알아서 웹앱으로 조립해주지는 않습니다. 브라우저가 이해할 수 있는 결과로 바꾸고, 요청에 맞는 페이지와 데이터를 전달하는 과정이 필요합니다.

웹 애플리케이션의 전체 구조는 화면·서버·데이터베이스로 이해하는 웹앱의 기본 구조에서 더 자세히 설명합니다.

개발 서버가 중간에서 웹앱을 준비해요

개발 중에는 개발 서버가 내 프로젝트와 브라우저 사이에서 일합니다.

프로젝트의 소스 코드
→ 개발 서버가 읽고 준비
→ 브라우저가 이해할 수 있는 결과 전달
→ 웹페이지 표시

개발 서버는 다음과 같은 일을 할 수 있습니다.

• 여러 코드 파일을 브라우저가 사용할 수 있게 준비한다.
• 주소에 맞는 페이지를 찾아서 보여준다.
• 서버에서 실행해야 하는 코드를 처리한다.
• 파일이 바뀌면 결과를 다시 만들고 브라우저에 반영한다.
• 개발 중 발생한 오류를 터미널에 보여준다.

그래서 Next.js 웹앱은 프로젝트 파일을 더블클릭하는 대신 개발 서버를 먼저 실행해야 합니다.

npm run dev는 무엇을 하나요?

Next.js 프로젝트에서 자주 사용하는 개발 서버 실행 요청이 npm run dev입니다.

npm run dev

각 단어의 세부 문법을 외울 필요는 없습니다. 지금은 “이 프로젝트의 개발용 서버를 시작해줘”라는 뜻으로 이해하면 충분해요.

npm run dev
→ 개발 서버 시작
→ 프로젝트 코드 준비
→ 접속할 localhost 주소 안내

직접 명령어를 입력하지 않고 AI에게 요청해도 됩니다.

이 프로젝트의 개발 서버를 실행해줘.
실행이 끝나면 브라우저에서 확인할 주소를 알려줘.
오류가 나면 임의로 설정을 바꾸지 말고 원인부터 쉽게 설명해줘.

AI가 서버를 실행한 터미널은 작업하는 동안 계속 켜두어야 합니다. 서버를 종료하면 해당 주소에서 웹앱을 볼 수 없어요.

localhost는 내 컴퓨터예요

개발 서버를 실행하면 다음과 같은 주소가 나옵니다.

http://localhost:3000

localhost는 지금 내가 사용하고 있는 컴퓨터를 가리키는 이름입니다.

localhost
→ 내 컴퓨터

브라우저에서 이 주소를 열면 인터넷 어딘가의 서버가 아니라 내 컴퓨터에서 실행 중인 개발 서버에 접속합니다.

따라서 내 컴퓨터의 localhost 주소를 다른 사람에게 보내도 그 사람은 같은 웹앱을 볼 수 없습니다. 다른 사람의 브라우저에서 localhost는 그 사람의 컴퓨터를 뜻하기 때문이에요.

내 컴퓨터에서만 보이는 페이지를 다른 사람도 볼 수 있게 만드는 과정은 배포입니다. localhost와 배포의 차이에서 그 흐름을 이어서 확인할 수 있습니다.

3000은 port예요

localhost 뒤에 붙은 3000은 port 번호입니다.

http://localhost:3000
                 └─ port

한 컴퓨터에서는 여러 프로그램이 동시에 통신할 수 있습니다. port는 들어온 요청을 어떤 프로그램이 받을지 구분하는 번호예요.

건물 주소와 호수를 떠올리면 쉽습니다.

localhost
→ 건물 주소: 어느 컴퓨터인가

3000
→ 호수: 그 컴퓨터의 어느 프로그램인가

예를 들어 두 개의 개발 서버를 동시에 실행하면 서로 다른 port를 사용할 수 있습니다.

http://localhost:3000
→ 첫 번째 웹앱

http://localhost:3001
→ 두 번째 웹앱

이미 다른 프로그램이 3000번 port를 사용하고 있다면 Next.js가 3001처럼 다른 번호를 선택할 수도 있습니다. 주소가 평소와 다르다고 오류인 것은 아니므로 터미널에 표시된 실제 주소를 확인하세요.

서버를 껐다가 다시 켜면 어떻게 되나요?

개발 서버는 프로젝트를 삭제하거나 저장하는 도구가 아닙니다. 현재 저장된 코드를 브라우저에서 사용할 수 있도록 실행하는 도구예요.

서버 종료
→ 웹앱 주소에 접속할 수 없음
→ 프로젝트 파일은 그대로 남아 있음

서버 다시 실행
→ 저장된 프로젝트를 다시 읽음
→ 웹앱 주소에 다시 접속 가능

Word를 종료해도 .docx 파일이 사라지지 않는 것과 비슷합니다. 개발 서버를 종료해도 작성한 코드는 없어지지 않아요.

서버를 직접 종료할 때는 실행 중인 터미널에서 Ctrl+C를 사용합니다. AI가 서버를 관리하고 있다면 다음처럼 요청해도 됩니다.

현재 실행 중인 개발 서버가 있는지 확인해줘.
있다면 어떤 주소에서 실행 중인지 알려줘.
새 서버를 중복으로 실행하지 마.

실행되지 않을 때 무엇을 확인할까요?

localhost가 열리지 않는다면 코드를 무작정 수정하기 전에 개발 서버의 상태를 확인하세요.

1. 개발 서버가 실행 중인가?
2. 터미널에 오류가 표시되어 있는가?
3. 터미널에 나온 주소와 port를 정확히 열었는가?
4. 같은 프로젝트의 서버를 여러 번 실행하지 않았는가?
5. 필요한 라이브러리가 설치되어 있는가?

AI에게는 다음처럼 요청할 수 있습니다.

localhost 페이지가 열리지 않아.

코드를 바로 수정하지 말고
개발 서버가 실행 중인지,
터미널에 어떤 오류가 있는지,
실제 접속 주소와 port가 무엇인지 먼저 확인해줘.

원인을 쉬운 말로 설명한 뒤 필요한 조치를 제안해줘.

Windows에서 스크립트를 실행할 권한이 없다는 오류가 나타나는 등 컴퓨터 설정 때문에 서버가 시작되지 않을 수도 있습니다. 이때 오류를 없애기 위해 보안 설정을 무작정 낮추지 마세요. 오류 메시지를 AI에게 보여주고 현재 환경에서 필요한 최소한의 해결 방법을 설명해달라고 요청하는 편이 안전합니다.

HTML, CSS, JavaScript와 개발 서버는 역할이 달라요

HTML, CSS, JavaScript는 브라우저가 화면과 동작을 표현할 때 사용하는 기본 언어입니다.

HTML
→ 화면의 구조

CSS
→ 화면의 디자인

JavaScript
→ 화면의 동작

개발 서버는 이 언어들을 대신하는 것이 아닙니다. 여러 소스 코드와 서버 기능을 브라우저가 사용할 수 있도록 준비하고 전달하는 역할을 합니다.

각 언어가 구체적으로 무슨 일을 하는지는 HTML, CSS, JavaScript의 역할에서 확인할 수 있습니다.

정리

• HTML 파일은 브라우저가 문서 파일을 직접 읽어서 열 수 있습니다.
• 정적 페이지는 미리 준비된 파일을 그대로 보여주는 방식입니다.
• Next.js 웹앱은 여러 코드와 서버 기능이 함께 작동하므로 실행 과정이 필요합니다.
• 개발 서버는 프로젝트 코드를 준비하고 브라우저에 전달합니다.
• npm run dev는 개발 서버를 시작하는 요청입니다.
• localhost는 내 컴퓨터를 뜻합니다.
• 3000은 내 컴퓨터에서 어떤 프로그램에 접속할지 구분하는 port입니다.
• 개발 서버를 종료해도 프로젝트 파일은 사라지지 않습니다.
• 페이지가 열리지 않으면 코드보다 서버 상태, 오류 메시지, 실제 주소를 먼저 확인하세요.

가장 중요한 차이는 다음과 같습니다.

HTML 파일
→ 브라우저가 파일을 직접 열 수 있음

Next.js 웹앱
→ 개발 서버가 프로젝트를 실행하고 결과를 전달
→ 브라우저는 localhost로 접속

웹앱을 “파일을 여는 문서”가 아니라 “여러 기능이 함께 실행되는 프로그램”으로 생각하면 왜 개발 서버가 필요한지 이해하기 쉬워집니다.