대부분 처음엔 "배포된 줄 안다"
npm run dev를 실행했습니다. 터미널에 뭔가 가득 출력됐습니다. 브라우저가 열리면서 앱이 나타났습니다.
"오, 드디어 됐다! 서비스가 만들어진 건가?"
친구에게 자랑하고 싶어서 링크를 복사했습니다. http://localhost:3000
친구에게 보냈습니다. 친구가 답했습니다. "이거 열리지 않는데?"
"왜 안 열리지? 방금 내 화면에서는 잘 됐는데..."
이 글은 localhost가 "기술적으로 무엇인가"가 아니라, "내 컴퓨터 안에서 앱이 실행된다는 것이 어떤 의미인가"를 이해하게 만드는 글입니다. TCP/IP나 네트워크 이론은 나오지 않습니다.
localhost는 무엇인가
가장 쉬운 한 줄 정의입니다.
인터넷 서버가 아니라, 내 컴퓨터 안에 만들어진 작은 서버입니다
npm run dev를 실행하는 순간, 내 컴퓨터 안에 작은 서버 하나가 켜집니다. 브라우저가 인터넷 어딘가에 있는 서버로 가는 것이 아니라, 내 컴퓨터 안에 있는 그 서버로 연결되는 것입니다. 그래서 나만 볼 수 있습니다.
🏠 가장 이해하기 쉬운 비유 — "내 방 안의 테스트 매장"
나만 들어갈 수 있고 밖에서는 보이지 않음
링크만 있으면 누구나 접속 가능
localhost라는 단어 자체의 의미도 직관적입니다. "local(내 컴퓨터) + host(서버)" — 내 컴퓨터가 서버 역할을 하는 것입니다. 그래서 인터넷 연결 없이도 localhost는 작동합니다.
3000은 무슨 숫자인가 — 포트 번호
localhost 뒤에 붙는 :3000이 무엇인지 많은 비개발자가 궁금해합니다.
🏢 아파트 비유로 이해하는 포트 번호
(내 컴퓨터)
(어떤 앱인지 구분)
포트 번호로 "어느 앱으로 연결할지" 구분합니다
🔢 실제로 자주 만나는 포트 번호들
3001, 5173, 8080 — 포트 번호가 달라도 작동 방식은 동일합니다. 터미널에 표시된 주소를 그대로 복사해 브라우저에 붙여넣으면 됩니다. 숫자 자체는 중요하지 않습니다.
npm run dev를 실행하면 실제로 무슨 일이 일어나는가
비개발자 눈에는 "명령어 입력 → 마법처럼 앱이 뜸"으로 보입니다. 실제로는 아래 흐름이 순서대로 일어납니다.
개발 서버가 내 컴퓨터 안에서 시작됩니다
Node.js가 프로젝트 코드를 읽어 서버를 실행합니다. 이 서버는 터미널이 열려 있는 동안만 작동합니다.
포트 번호를 배정합니다 (기본: 3000)
서버가 localhost:3000에서 대기 상태가 됩니다. 3000이 이미 사용 중이면 3001로 자동 이동합니다.
터미널에 주소가 표시됩니다
아래처럼 출력되면 서버가 준비된 것입니다.
브라우저에서 주소로 접속합니다
브라우저 주소창에 http://localhost:3000을 입력하면 내 컴퓨터 안의 서버에서 앱을 가져와 화면에 보여줍니다. 인터넷이 관여하지 않습니다.
코드를 저장하면 자동으로 화면이 새로고침됩니다
이것이 Hot Reload입니다. 다음 섹션에서 자세히 설명합니다.
localhost에서 실행 중인 앱은 테스트와 개발을 위한 임시 공간입니다. 속도 최적화도 안 되어 있고, 보안 설정도 프로덕션 수준이 아닙니다. 실제 서비스로 쓰려면 반드시 배포 과정을 거쳐야 합니다.
왜 다른 사람은 볼 수 없는가
localhost는 글자 그대로 "나(local)의 서버(host)"입니다. 이 주소는 인터넷을 통해 외부로 나가지 않습니다. 내 컴퓨터 안에서만 통하는 주소입니다.
나만 볼 수 있음
누구나 볼 수 있음
즉 localhost는 "오픈 전 리허설 무대"이고, 배포는 "실제 공연"입니다. 리허설에서 충분히 확인한 후 공연에 올리는 것이 올바른 흐름입니다. 이 구조가 이해되면 왜 Vercel 같은 배포 플랫폼이 필요한지도 자연스럽게 이해됩니다.
저장하면 자동으로 반영된다 — Hot Reload
localhost 개발 환경의 가장 강력한 기능이 있습니다. 코드를 수정하고 저장(Ctrl+S)하면 브라우저가 자동으로 새로고침되어 변경 사항이 즉시 반영됩니다. 이것을 Hot Reload(또는 HMR — Hot Module Replacement)라고 합니다.
⚡ Hot Reload가 바이브 코딩에서 특히 중요한 이유
AI에게 "헤더 색상 바꿔줘"라고 요청하면 AI가 코드를 수정합니다. 저장하는 순간 브라우저에서 즉시 결과를 확인할 수 있습니다. "아 이 색은 아니다"라는 것을 바로 알 수 있고, 다시 AI에게 피드백을 줄 수 있습니다.
💡 배포된 사이트는 코드를 수정해도 자동으로 바뀌지 않습니다. GitHub에 푸시하고 재배포해야 반영됩니다. 개발 중에 localhost를 쓰는 가장 큰 이유 중 하나가 바로 이 즉각적인 피드백 때문입니다.
비개발자가 가장 많이 오해하는 것들
이 오해들을 미리 알면 실제 상황에서 당황하지 않습니다.
"localhost가 열렸으니 배포 완료된 것이다"
가장 흔한 오해입니다. localhost는 내 컴퓨터 안에서만 작동하는 개발 환경입니다.
"빨간 에러 화면이 뜨면 모든 게 망했다"
localhost에서 뜨는 빨간 에러 오버레이는 "개발 모드에서 문제가 있다"는 친절한 알림입니다. 코드 파일은 전혀 망가지지 않습니다.
"브라우저를 닫으면 프로젝트가 사라진다"
브라우저를 닫아도 코드 파일은 내 컴퓨터에 그대로 남아 있습니다.
"3001로 바뀌면 오류가 난 것이다"
localhost:3001, 5173 같은 다른 포트 번호가 뜨면 당황하는 경우가 많습니다.
"localhost에서 됐으니 배포해도 똑같이 될 것이다"
localhost에서 잘 작동하더라도 배포 후 문제가 생기는 경우가 있습니다.
결국 중요한 것은 "로컬 실행 감각"
기술적인 내용보다 더 중요한 것이 있습니다. "지금 내 앱이 어디서 실행되고 있는가"를 감각적으로 아는 것입니다.
바이브 코딩에서 "로컬 실행 감각"이 생기면 이런 것들이 자연스러워집니다:
localhost:3000은 단순한 숫자가 아닙니다. 비개발자가 처음으로 "내가 직접 앱을 실행하고 있다"는 감각을 얻게 되는 시작점입니다. 이 감각이 생기면 이후 모든 개발 흐름이 훨씬 자연스럽게 연결됩니다.
관련 글 → [[터미널 비개발자 최소 생존 가이드 — 바이브 코딩에서 실제로 쓰는 명령어 5가지]] — npm run dev 실행과 Ctrl+C 종료 관련 글 → [[.env 파일 완전 가이드 — 비개발자가 반드시 알아야 할 환경 변수 설정과 보안]] — 배포 환경 변수 설정
📌 핵심 정리
- localhost는 인터넷이 아닙니다. npm run dev를 실행하면 내 컴퓨터 안에 작은 서버가 만들어지고, 브라우저가 그 서버에 접속하는 구조입니다. 다른 사람은 볼 수 없습니다.
- :3000은 포트 번호입니다. 아파트 호수처럼 같은 컴퓨터에서 여러 앱을 구분하는 번호입니다. 3001, 5173 등 다른 숫자가 나와도 정상입니다. 터미널에 표시된 주소를 그대로 쓰면 됩니다.
- 코드를 수정하고 저장하면 localhost 화면이 자동으로 새로고침됩니다(Hot Reload). 이것이 개발 중에 localhost를 쓰는 가장 큰 이유 중 하나입니다.
- 다른 사람이 볼 수 있게 하려면 Vercel, Netlify 같은 배포 플랫폼을 통해 별도로 배포해야 합니다. localhost는 "리허설 무대", 배포는 "실제 공연"입니다.
- localhost에서 잘 됐어도 배포 후 오류가 날 수 있습니다. 가장 흔한 원인은 Vercel에 환경 변수가 설정되지 않은 것입니다. 배포 전에 확인하세요.
❓ 자주 묻는 질문
localhost:3000은 인터넷에 올라간 건가요?
아닙니다. localhost는 인터넷이 아니라 내 컴퓨터 안에서만 열리는 임시 개발 공간입니다. npm run dev를 실행하면 내 컴퓨터 안에 작은 서버가 만들어지고, 브라우저가 그 서버에 접속하는 구조입니다. 다른 사람에게 링크를 공유해도 접속할 수 없습니다. 다른 사람이 볼 수 있게 하려면 Vercel, Netlify 같은 배포 플랫폼을 통해 인터넷에 올려야 합니다.
localhost 뒤의 숫자 3000은 무슨 의미인가요?
포트(Port) 번호입니다. 내 컴퓨터 안에서 여러 앱이 동시에 실행될 수 있는데, 어떤 앱으로 연결할지 구분하는 번호입니다. 아파트 건물(내 컴퓨터)에서 호수(포트 번호)로 특정 집을 찾는 것과 비슷합니다. 3000은 Next.js의 기본 포트 번호이고, 이미 사용 중이면 3001, 3002처럼 자동으로 바뀝니다.
npm run dev를 실행한 후 브라우저를 닫으면 앱이 사라지나요?
아닙니다. 브라우저를 닫아도 코드 파일은 그대로 내 컴퓨터에 남아 있습니다. 다만 npm run dev로 실행한 개발 서버는 터미널을 닫거나 Ctrl+C를 누르면 종료됩니다. 서버가 종료된 상태에서는 localhost:3000에 다시 접속할 수 없지만, npm run dev를 다시 실행하면 바로 복구됩니다.
localhost:3000 대신 localhost:3001이 뜨는 이유가 뭔가요?
이미 3000번 포트를 다른 프로그램이 사용 중이기 때문입니다. 보통 이전에 npm run dev를 실행했는데 Ctrl+C로 종료하지 않고 터미널을 그냥 닫은 경우에 발생합니다. 3001이 뜨는 건 오류가 아니라 정상 동작입니다. 터미널에 표시된 주소를 그대로 복사해 브라우저에 붙여넣으면 됩니다. 컴퓨터를 재시작하면 다시 3000이 됩니다.
지금 npm run dev를 실행하고
localhost:3000을 열어보세요
이제 이 주소가 무엇인지 압니다.
내 컴퓨터 안에서 앱이 실행되고 있는 것입니다.
코드를 한 줄 바꾸고 저장해보세요. 화면이 바뀝니다.
댓글 쓰기