localhost 3000 안됨? 5가지 원인별 해결 방법 총정리 (2026)

npm run dev를 실행하고 브라우저에서 localhost:3000을 열었는데 “사이트에 연결할 수 없음”이 뜨면 당황스럽습니다. 특히 바이브코딩으로 처음 Next.js 프로젝트를 만든 직후라면, 설치 자체가 잘못된 건 아닌지 불안해지기 쉽습니다. 하지만 localhost 3000 안됨 문제는 원인이 명확하고, 대부분 5분 안에 해결할 수 있습니다. 이 글에서는 서버 미실행, 포트 충돌, 방화벽, 브라우저 캐시, 코드 에러까지 5가지 원인별 해결 방법을 순서대로 안내합니다.

🔍 localhost 3000 안됨 — 5단계 진단 순서

문제를 만났을 때 무작정 설정을 바꾸거나 재설치하는 것보다, 원인을 순서대로 좁혀가는 것이 훨씬 빠릅니다. 아래 5단계를 위에서부터 차례대로 확인하세요. 80% 이상은 1~2단계에서 원인이 잡힙니다.

1. 터미널에 서버가 실행 중인가? — npm run dev 출력에 localhost:3000 또는 포트 번호가 표시돼야 합니다.
2. 터미널에 에러 메시지가 있는가? — 빨간색 텍스트나 Error 키워드가 보이면 서버가 시작되지 않은 겁니다.
3. 포트 3000을 다른 프로세스가 쓰고 있는가? — 포트 점유 확인 명령으로 진단합니다.
4. 브라우저 주소를 정확히 입력했는가? — http://localhost:3000인지 확인합니다(https가 아닌 http).
5. 방화벽이나 보안 소프트웨어가 차단하는가? — 방화벽 설정을 확인합니다.

이 다섯 단계를 순서대로 점검하면 대부분의 localhost 3000 안됨 상황에서 원인을 특정할 수 있습니다. 각 단계의 구체적인 해결 방법은 아래 섹션에서 다룹니다.

📖 먼저 알아두면 좋은 핵심 용어

트러블슈팅 과정에서 자주 등장하는 용어를 정리했습니다. 이 용어만 알면 에러 메시지를 해석하는 데 큰 도움이 됩니다.

🖥️ 개발 서버가 실행되지 않았을 때

localhost 3000 안됨 문제의 가장 흔한 원인입니다. 서버가 시작되지 않았는데 브라우저에서 접속을 시도하면 당연히 연결이 안 됩니다. 터미널부터 확인하세요.

🟢 서버 실행 여부 확인 방법

npm run dev(또는 pnpm dev, yarn dev)를 실행한 뒤 아래와 비슷한 메시지가 터미널에 표시돼야 합니다.

  ▲ Next.js 14.x.x
  - Local:        http://localhost:3000

 ✓ Ready in 2.3s

“Ready” 메시지가 보이지 않고 터미널이 프롬프트 상태($ 또는 >)로 돌아갔다면 서버가 시작되지 않은 것입니다. 이 경우 터미널 위쪽에 출력된 에러 메시지를 확인하면 원인을 알 수 있습니다.

📦 패키지가 설치되지 않은 경우

의존성 패키지가 없으면 npm run dev 실행 시 MODULE_NOT_FOUND 에러가 발생합니다. 프로젝트를 처음 클론(다운로드)했거나, node_modules 폴더를 삭제한 뒤 다시 설치하지 않았기 때문입니다. 프로젝트 폴더에서 아래 명령으로 패키지를 설치하세요.

# npm 사용 시
npm install

# pnpm 사용 시
pnpm install

node_modules 폴더가 생성되고 에러 없이 완료되면 npm run dev를 다시 실행합니다. 터미널에 “Ready” 메시지가 출력되면 정상입니다.

📂 프로젝트 폴더 바깥에서 실행한 경우

npm run dev는 package.json이 있는 프로젝트 루트 디렉토리에서 실행해야 합니다. 다른 디렉토리에서 실행하면 Missing script: "dev" 에러가 납니다. 자신이 어디에 있는지 모를 때는 현재 위치를 먼저 확인하세요.

# 현재 위치 확인
pwd

# 프로젝트 폴더로 이동
cd my-app

# package.json이 있는지 확인
ls package.json

package.json이 보이는 디렉토리에서 npm run dev를 다시 실행하면 됩니다. 터미널 기본 사용법이 익숙하지 않다면 해당 가이드를 먼저 살펴보세요.

🔌 포트 3000이 이미 사용 중일 때

다른 프로그램이나 이전에 종료되지 않은 개발 서버가 포트 3000을 점유하고 있으면 새 서버가 시작되지 않습니다. 터미널에 EADDRINUSE 에러가 표시되거나, Next.js가 자동으로 3001, 3002 등 다른 포트로 전환하는 경우가 이에 해당합니다.

🪟 Windows에서 포트 확인 및 해제

PowerShell 또는 명령 프롬프트에서 포트 3000을 사용 중인 프로세스를 찾아 종료할 수 있습니다.

# 포트 3000을 사용 중인 프로세스 확인
netstat -ano | findstr :3000

# 출력 예시: TCP  0.0.0.0:3000  0.0.0.0:0  LISTENING  12345
# 마지막 숫자(12345)가 PID(프로세스 ID)

# 해당 프로세스 종료
taskkill /PID 12345 /F

findstr :3000 결과가 비어 있으면 포트 3000을 사용하는 프로세스가 없다는 뜻입니다. 이 경우 다른 원인을 점검하세요.

🍎 macOS에서 포트 확인 및 해제

macOS에서는 lsof 명령을 사용합니다. 터미널을 열고 아래 명령을 실행하세요.

# 포트 3000을 사용 중인 프로세스 확인
lsof -i :3000

# 출력 예시: node  12345  user  22u  IPv6  ...  (LISTEN)
# 두 번째 열(12345)이 PID

# 해당 프로세스 종료
kill -9 12345

프로세스를 종료한 뒤 lsof -i :3000을 다시 실행해서 결과가 비어 있으면 포트가 해제된 것입니다. npm run dev를 다시 실행하면 정상적으로 3000번 포트에서 서버가 시작됩니다.

🔄 다른 포트로 실행하는 방법

포트 3000을 반드시 고수할 필요는 없습니다. 점유된 프로세스를 찾기 귀찮거나, 의도적으로 여러 프로젝트를 동시에 실행하고 싶다면 다른 포트를 지정하면 됩니다.

# Next.js에서 포트 변경
npx next dev -p 3001

# 또는 환경 변수로 지정
PORT=3001 npm run dev

브라우저에서 http://localhost:3001로 접속하면 됩니다. 변경한 포트 번호를 잊지 않도록 터미널의 출력 메시지를 확인하세요.

🛡️ 방화벽·보안 소프트웨어가 차단할 때

서버가 정상 실행 중이고 포트도 비어 있는데 브라우저에서 접속이 안 된다면, 방화벽이 Node.js의 네트워크 활동을 차단하고 있을 수 있습니다. 방화벽은 외부 침입을 막기 위한 보안 기능인데, 때로는 내 컴퓨터에서 실행하는 개발 서버까지 차단합니다.

🪟 Windows 방화벽 설정

1. Windows 검색에서 “Windows Defender 방화벽”을 검색합니다.
2. 왼쪽 메뉴에서 “Windows Defender 방화벽을 통해 앱 또는 기능 허용”을 클릭합니다.
3. 목록에서 “Node.js” 또는 “Node.js JavaScript Runtime”을 찾습니다.
4. “개인” 및 “공용” 체크박스가 모두 선택돼 있는지 확인합니다.
5. 목록에 없으면 “다른 앱 허용” 버튼을 클릭하고 Node.js 실행 파일을 추가합니다.

Node.js를 허용한 뒤 개발 서버를 다시 시작하고 브라우저에서 접속해보세요. 바이브코딩 Windows 환경설정 가이드에서 방화벽 관련 설정을 더 자세히 다루고 있습니다.

🍎 macOS 방화벽 설정

1. 시스템 설정 → 네트워크 → 방화벽을 엽니다.
2. 방화벽이 켜져 있다면 “옵션”을 클릭합니다.
3. “들어오는 연결을 받을 수 있도록 허용된 앱” 목록에 Node.js가 있는지 확인합니다.
4. 없으면 “+” 버튼을 눌러 Node.js를 추가하거나, “서명된 소프트웨어의 수신 연결 자동 허용”을 체크합니다.

변경 후 터미널에서 개발 서버를 다시 시작하면 됩니다.

🦠 서드파티 백신이 차단하는 경우

Norton, Kaspersky, V3 같은 서드파티 백신이 Node.js의 네트워크 활동을 의심스러운 것으로 판단해 차단하는 경우가 있습니다. 백신 설정에서 Node.js 실행 파일을 예외 목록에 추가하거나, 일시적으로 실시간 보호를 끄고 테스트해보세요. 백신을 끈 상태에서 접속이 되면 백신이 원인이라는 뜻이므로, 예외 설정을 추가한 뒤 다시 활성화하면 됩니다.

🌐 브라우저 문제로 접속이 안 될 때

서버도 정상이고 포트도 문제없는데 브라우저에서만 접속이 안 되는 경우가 있습니다. 주소 오타, 캐시, 확장 프로그램이 주요 원인입니다.

🔗 주소 입력 실수 점검

의외로 흔한 실수가 주소를 잘못 입력하는 것입니다. 개발 서버는 기본적으로 SSL을 사용하지 않으므로 https가 아닌 http를 써야 합니다.

일부 브라우저(Chrome 등)가 http://를 자동으로 https://로 변환하는 경우가 있으므로 주소창을 다시 확인하세요.

🗑️ 브라우저 캐시 지우기

이전에 접속했던 페이지가 캐시되면 오래된 응답을 보여주거나, HSTS 설정이 HTTPS로 강제 리디렉션할 수 있습니다. 아래 순서로 캐시를 정리하세요.

1. Ctrl+Shift+Delete(macOS: Cmd+Shift+Delete)로 브라우저 데이터 삭제 창을 엽니다.
2. “캐시된 이미지 및 파일”을 선택하고 삭제합니다.
3. 또는 시크릿/프라이빗 모드(Ctrl+Shift+N)에서 http://localhost:3000을 열어봅니다.

시크릿 모드에서 정상 접속된다면 브라우저 캐시나 확장 프로그램이 원인입니다. 정상 접속이 확인되면 일반 모드에서 캐시를 완전히 삭제한 뒤 다시 시도하세요.

🧩 확장 프로그램 충돌

광고 차단기, VPN 확장, 보안 확장 프로그램이 localhost 접속을 차단하는 경우가 있습니다. 모든 확장 프로그램을 비활성화한 뒤 다시 접속해보세요. 문제가 해결되면 확장 프로그램을 하나씩 켜면서 범인을 좁힐 수 있습니다.

💻 코드 에러로 서버가 종료됐을 때

개발 서버가 시작됐다가 코드 에러 때문에 즉시 종료되는 경우도 있습니다. 서버가 “실행 중인 것 같은데” 접속이 안 되면, 터미널을 확인해서 에러 메시지가 없는지 살펴보세요.

🔴 자주 발생하는 코드 에러

에러 메시지에 파일 경로와 줄 번호가 표시됩니다. 해당 위치를 VS Code에서 열어 수정한 뒤 저장하면 Next.js 개발 서버가 자동으로 다시 컴파일합니다. 컴파일이 성공하면 별도의 재시작 없이 바로 접속할 수 있습니다.

📝 .env 파일 관련 에러

환경 변수 파일(.env.local, .env)의 문법이 틀리면 서버가 시작 직후 종료될 수 있습니다. 등호(=) 주변에 공백이 있거나 따옴표가 짝이 맞지 않으면 파싱에 실패하기 때문입니다.

# 올바른 형식
DATABASE_URL=postgresql://localhost:5432/mydb
NEXT_PUBLIC_API_URL="https://api.example.com"

# 잘못된 형식
DATABASE_URL = postgresql://localhost:5432/mydb   # 등호 주변 공백
NEXT_PUBLIC_API_URL=https://api.example.com"      # 따옴표 불일치

등호 양옆의 공백을 제거하고, 따옴표는 열었으면 반드시 닫아야 합니다. 수정 후 서버를 다시 시작해서 “Ready” 메시지가 뜨면 해결입니다.

✅ 문제 해결 점검 목록

아래 항목을 순서대로 확인하며 문제를 좁혀보세요. 하나씩 체크할 때마다 원인이 명확해집니다.

• 터미널에서 npm run dev 실행 후 “Ready” 메시지가 출력되는가
• 터미널에 빨간색 에러 메시지가 없는가
• http://localhost:3000으로 접속하고 있는가 (https 아님)
• 포트 3000을 사용 중인 다른 프로세스가 없는가
• 시크릿 모드 브라우저에서도 접속이 안 되는가
• 방화벽에서 Node.js가 허용돼 있는가
• node_modules 폴더가 프로젝트 안에 존재하는가
• package.json이 있는 디렉토리에서 실행했는가

모든 항목을 통과했는데도 접속이 안 되면, 컴퓨터를 재부팅한 뒤 처음부터 다시 시도해보세요. 백그라운드에 남아 있던 프로세스가 정리되면서 해결되는 경우가 있습니다.

🪤 자주 하는 실수와 예방법

localhost 3000 안됨 문제를 겪은 분들이 공통적으로 저지르는 실수 패턴입니다. 미리 알아두면 같은 상황을 반복하지 않을 수 있습니다.

💡 OS별 특수한 상황

운영체제에 따라 localhost 3000 안됨 문제의 원인이 다를 수 있습니다. Windows와 macOS 각각의 고유한 함정을 정리했습니다.

🪟 Windows 전용 문제

WSL(Windows Subsystem for Linux)에서 실행하는 경우: WSL 안에서 개발 서버를 실행하면 Windows 브라우저에서 localhost:3000으로 바로 접속이 안 될 수 있습니다. WSL2에서는 대부분 자동으로 포워딩되지만, 안 되는 경우에는 WSL의 IP 주소를 확인해서 직접 접속하세요.

# WSL 안에서 IP 확인
hostname -I
# 출력 예시: 172.20.0.2

Windows 브라우저에서 http://172.20.0.2:3000으로 접속하면 됩니다. IP가 매번 바뀔 수 있으므로 접속 전마다 확인하는 습관을 들이세요.

Windows Defender SmartScreen 팝업: 처음 Node.js를 실행할 때 SmartScreen이 네트워크 접근을 차단할 수 있습니다. “허용” 또는 “액세스 허용”을 클릭하세요. 이 팝업을 무시하거나 “거부”를 누르면 이후 서버가 네트워크에 접근하지 못합니다.

🍎 macOS 전용 문제

AirPlay Receiver 포트 점유: macOS Monterey 이상에서 AirPlay Receiver가 포트 5000을 점유합니다. 포트 3000에는 직접 영향이 없지만, Flask 같은 프레임워크에서 포트 5000을 기본으로 사용하는 경우 충돌합니다. 시스템 설정 → 일반 → AirDrop 및 Handoff에서 AirPlay Receiver를 끌 수 있습니다.

키체인 접근 팝업: 처음 개발 서버를 실행할 때 키체인 접근 허용 팝업이 나타날 수 있습니다. “허용”을 클릭하세요. “거부”를 눌렀다면 키체인 접근 앱에서 해당 항목을 삭제하고 다시 시도하면 됩니다.

⚡ 개발 서버 안정 운영 팁

localhost 접속 문제를 미리 예방하고, 개발 흐름을 끊기지 않게 유지하는 팁입니다.

• 서버 종료는 Ctrl+C로: 터미널 창을 닫는 대신 반드시 Ctrl+C로 서버를 종료하세요. 창을 그냥 닫으면 프로세스가 백그라운드에 남아 다음 실행 시 포트 충돌이 발생합니다.
• 고정 포트 지정: .env.local에 PORT=3000을 명시하면 포트가 매번 바뀌는 혼란을 줄일 수 있습니다. 여러 프로젝트를 동시에 다루는 경우 각 프로젝트에 다른 포트를 지정하세요(3000, 3001, 3002 등).
• 터미널 분할 사용: VS Code의 내장 터미널을 분할해서 한쪽에는 서버, 다른 쪽에는 명령 실행용으로 사용하면 서버 상태를 항상 눈으로 확인할 수 있습니다.
• node_modules 재설치: 원인을 알 수 없는 에러가 반복되면 node_modules와 package-lock.json(또는 pnpm-lock.yaml)을 삭제한 뒤 npm install을 다시 실행해보세요. 의존성 꼬임이 풀리는 경우가 많습니다.

다른 에러로 막힐 때도 방식은 같아요. 막혔을 때 5분 디버깅 5단계로 원인부터 추리면 빠릅니다.

면책조항

여기까지 읽어주셔서 감사합니다. localhost 3000 안됨 문제가 해결되셨길 바랍니다. 개발 환경 트러블슈팅은 처음엔 막막하지만, 몇 번 경험하면 금방 익숙해집니다.

❓ FAQ

질문을 누르면 답변이 펼쳐집니다.

🔗 관련 글

• 바이브코딩 시작 전 개발환경 세팅 완벽 가이드
• Node.js 설치부터 바이브코딩 시작까지 3단계
• 터미널 처음 사용하는 비전공자를 위한 바이브코딩 가이드
• 바이브코딩용 VS Code 설정 가이드
• 바이브코딩 Windows 환경설정 가이드

📑 참고 자료

• Next.js 공식 문서 — Installation & Development Server
• MDN Web Docs — What is localhost?
• Node.js 공식 문서 — Debugging Guide

Brandon

IT 기획 10년차 / 비전공자를 위한 바이브코딩 블로그 운영 / vibe-start.com 제작

Building VibeStart — the fastest path for non-devs into AI coding. Launching on Product Hunt 2026-05-26.

vibe-start.com