🚨 localhost:3000에 접속이 안 되는 상황

npm run dev를 실행하고 브라우저에서 localhost:3000을 열었는데 "사이트에 연결할 수 없음" 또는 빈 화면이 나타나면 개발 진행이 멈춥니다. 특히 처음 Next.js 프로젝트를 만들고 개발 서버를 실행한 직후에 이 문제를 만나면 설치가 잘못된 것인지 불안해지기 쉽습니다.

이 글은 localhost:3000이 안 열리는 원인을 체계적으로 진단하고, 각 상황에 맞는 해결 방법을 안내합니다. 원인은 크게 다섯 가지로 나뉩니다: 서버 미실행, 포트 충돌, 방화벽 차단, 브라우저 문제, 코드 에러입니다.

🔍 진단 순서 한눈에 보기

문제를 만났을 때 아래 순서대로 확인하면 가장 빠르게 원인을 찾을 수 있습니다.

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

이 다섯 단계만 순서대로 점검하면 대부분의 상황에서 원인을 특정할 수 있습니다.

🔑 핵심 용어 정리

용어	의미
localhost	내 컴퓨터 자체를 가리키는 호스트명, IP 주소로는 127.0.0.1
포트(port)	네트워크 통신에서 특정 서비스를 구분하는 번호, 개발 서버는 주로 3000번 사용
개발 서버	코드 변경을 실시간으로 반영하며 로컬에서 웹 앱을 실행하는 서버
프로세스	실행 중인 프로그램 단위, 각 프로세스는 특정 포트를 점유할 수 있음
방화벽	네트워크 연결을 허용하거나 차단하는 보안 시스템

🖥️ 개발 서버가 실행되지 않은 경우

가장 흔한 원인입니다. 브라우저에서 localhost:3000을 열기 전에 터미널에서 개발 서버가 정상적으로 시작됐는지 확인해야 합니다.

📌 서버 실행 여부 확인

터미널에서 npm run dev(또는 pnpm dev, yarn dev)를 실행한 뒤 아래와 같은 메시지가 보여야 합니다.

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

 ✓ Ready in 2.3s

이 메시지가 보이지 않고 터미널이 프롬프트 상태($ 또는 >)로 돌아갔다면 서버가 시작되지 않은 것입니다. 에러 메시지를 확인하세요.

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

npm run dev 실행 시 MODULE_NOT_FOUND 에러가 나오면 의존성 패키지가 설치되지 않은 상태입니다. 프로젝트 폴더에서 패키지 설치를 먼저 진행하세요.

npm install
# 또는
pnpm install

node_modules 폴더가 생성되고 에러 없이 완료되면 npm run dev를 다시 실행하세요. 서버가 정상 시작되면 해결입니다.

📌 프로젝트 폴더가 아닌 곳에서 실행한 경우

npm run dev는 package.json이 있는 프로젝트 루트 디렉토리에서 실행해야 합니다. 다른 디렉토리에서 실행하면 Missing script: "dev" 에러가 발생합니다.

# 현재 위치 확인
pwd

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

# package.json 존재 확인
ls package.json

package.json이 보이는 디렉토리에서 npm run dev를 실행하세요.

🔌 포트 3000이 이미 사용 중인 경우

다른 프로그램이나 이전에 종료되지 않은 개발 서버가 포트 3000을 점유하고 있으면 새 서버가 시작되지 않거나 다른 포트로 자동 전환됩니다. Next.js는 포트 3000이 사용 중이면 3001, 3002 등으로 자동 변경하지만, 이전 버전이나 다른 프레임워크에서는 에러가 발생할 수 있습니다.

🪟 Windows에서 포트 확인 및 해제

# 포트 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에서 포트 확인 및 해제

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

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

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

프로세스를 종료한 뒤 lsof -i :3000을 다시 실행하세요. 결과가 비어 있으면 포트가 해제된 것이며, npm run dev를 다시 실행하면 됩니다.

📌 다른 포트로 실행하기

포트 3000 대신 다른 포트를 사용해도 됩니다. Next.js에서는 -p 옵션으로 포트를 지정할 수 있습니다.

npx next dev -p 3001
# 또는 package.json의 dev 스크립트를 수정하지 않고
PORT=3001 npm run dev

브라우저에서 http://localhost:3001로 접속하세요.

🛡️ 방화벽 및 보안 소프트웨어가 차단하는 경우

방화벽이 로컬 서버의 네트워크 연결을 차단하면 서버는 실행 중이지만 브라우저에서 접속이 안 됩니다.

🪟 Windows 방화벽 확인

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

Node.js를 허용한 뒤 개발 서버를 다시 시작하고 브라우저에서 접속해보세요.

🍎 macOS 방화벽 확인

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

변경 후 터미널에서 개발 서버를 다시 시작하세요.

📌 보안 소프트웨어(백신)가 차단하는 경우

일부 서드파티 백신(Norton, Kaspersky, V3 등)이 Node.js의 네트워크 활동을 의심스러운 것으로 판단해 차단할 수 있습니다. 백신 설정에서 Node.js 실행 파일을 예외 목록에 추가하거나, 일시적으로 실시간 보호를 끄고 테스트해보세요. 백신을 껐을 때 접속이 되면 백신이 원인인 것입니다.

🌐 브라우저 관련 문제

서버가 정상 실행 중이고 포트도 문제없는데 브라우저에서만 접속이 안 되는 경우가 있습니다.

📌 주소 입력 확인

흔한 실수 중 하나는 주소를 잘못 입력하는 것입니다. 아래 사항을 확인하세요.

올바른 주소	잘못된 주소
`http://localhost:3000`	`https://localhost:3000` (HTTPS 아님)
`http://localhost:3000`	`http://localhost:3000/` 끝에 경로 오타
`http://localhost:3000`	`http://localhos:3000` (오타)
`http://127.0.0.1:3000`	`http://0.0.0.0:3000` (일부 환경에서 동작 안 함)

https가 아닌 http를 사용해야 합니다. 개발 서버는 기본적으로 SSL을 사용하지 않습니다. 일부 브라우저가 http://를 자동으로 https://로 변환하는 경우가 있으므로 주소창을 다시 확인하세요.

📌 브라우저 캐시 지우기

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

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

시크릿 모드에서 정상 접속된다면 브라우저 캐시나 확장 프로그램이 원인입니다.

📌 브라우저 확장 프로그램 충돌

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

💻 코드 에러로 서버가 종료된 경우

개발 서버가 시작됐다가 코드 에러로 인해 즉시 종료되는 경우도 있습니다. 터미널의 에러 메시지를 확인하세요.

📌 자주 발생하는 코드 에러

에러 메시지	원인	해결 방법
`SyntaxError: Unexpected token`	코드 문법 오류	에러가 가리키는 파일과 줄 번호를 확인하고 수정
`Error: Cannot find module`	import 경로가 잘못됨	파일명과 경로를 다시 확인
`TypeError: Cannot read properties of null`	null 참조 에러	해당 변수가 초기화됐는지 확인
`EADDRINUSE`	포트가 이미 사용 중	위의 포트 해제 방법 참고

에러 메시지의 파일 경로와 줄 번호를 확인하면 문제 지점을 빠르게 찾을 수 있습니다. 수정 후 저장하면 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"     # 따옴표 불일치

✅ 문제 해결 점검 목록

각 항목을 순서대로 확인하며 문제를 좁혀보세요.

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

🪤 자주 하는 실수와 예방

실수	증상	예방법
터미널을 닫고 브라우저만 열어둠	서버가 중단되어 접속 불가	개발 중에는 터미널을 항상 열어두세요
여러 터미널에서 동시에 `npm run dev` 실행	포트 충돌로 두 번째 서버 실패	하나의 터미널에서만 서버를 실행하세요
프로젝트 폴더 바깥에서 `npm run dev` 실행	"Missing script" 에러	`cd`로 프로젝트 폴더 안으로 이동한 뒤 실행하세요
`https://`로 접속	SSL 인증서 에러 또는 접속 불가	개발 서버는 `http://`를 사용하세요
패키지 설치 없이 바로 서버 실행	MODULE_NOT_FOUND 에러	`npm install`을 먼저 실행하세요

🔄 OS별 특수한 상황

🪟 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으로 접속하면 됩니다.

Windows Defender SmartScreen이 차단하는 경우: 처음 Node.js를 실행할 때 SmartScreen이 네트워크 접근을 차단할 수 있습니다. "허용" 또는 "액세스 허용"을 클릭하세요.

🍎 macOS 전용 문제

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

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

⚡ VibeStart로 환경 문제 예방하기

개발 환경 세팅이 처음이라면 VibeStart에서 운영체제에 맞는 설치 가이드를 따라가세요. Node.js 설치, PATH 설정, 기본 프로젝트 생성까지 단계별로 안내하므로 localhost 접속 문제의 주요 원인인 환경 설정 실수를 미리 방지할 수 있습니다.

⚠️ 면책조항: 이 글의 내용은 2026년 4월 기준으로 작성되었습니다. 운영체제 업데이트, 브라우저 변경, Next.js 버전 업데이트에 따라 동작이 달라질 수 있습니다. 문제가 지속되면 각 도구의 공식 문서를 확인하세요.

❓ 자주 묻는 질문

Q. localhost:3000 대신 다른 포트 번호가 표시되는데 정상인가요?

네, 정상입니다. 포트 3000이 이미 사용 중이면 Next.js가 자동으로 3001, 3002 등 빈 포트를 찾아 실행합니다. 터미널에 표시된 포트 번호로 접속하세요.

Q. localhost와 127.0.0.1의 차이가 뭔가요?

둘 다 내 컴퓨터를 가리킵니다. localhost는 호스트명이고 127.0.0.1은 IPv4 주소입니다. 대부분의 경우 동일하게 동작하지만, 드물게 localhost로 접속이 안 되면 127.0.0.1:3000을 시도해보세요.

Q. 서버는 실행 중인데 "이 사이트에 연결할 수 없음"이 뜹니다.

방화벽이 차단하고 있거나, 브라우저가 https://로 자동 리디렉션하고 있을 수 있습니다. 시크릿 모드에서 http://localhost:3000을 열어보고, 방화벽에서 Node.js를 허용했는지 확인하세요.

Q. npm run dev가 아무런 메시지 없이 바로 종료됩니다.

package.json에 "dev" 스크립트가 올바르게 정의돼 있는지 확인하세요. Next.js 프로젝트라면 "dev": "next dev"로 설정돼 있어야 합니다. 빈 스크립트이거나 오타가 있으면 아무 동작 없이 종료됩니다.

Q. 포트를 변경하면 다른 설정도 바꿔야 하나요?

일반적으로 개발 서버의 포트만 변경하면 됩니다. 다만 환경 변수에 포트 번호를 하드코딩해뒀거나, API 콜백 URL에 포트가 지정돼 있다면 해당 설정도 함께 변경해야 합니다.

Q. 다른 기기(스마트폰 등)에서 localhost:3000에 접속할 수 있나요?

같은 네트워크에 연결돼 있다면 가능합니다. 내 컴퓨터의 IP 주소를 확인한 뒤(ipconfig 또는 ifconfig), 다른 기기에서 http://192.168.x.x:3000으로 접속하세요. 방화벽에서 해당 포트가 허용돼 있어야 합니다.

Q. 서버를 종료하지 않고 터미널을 닫았는데 포트가 계속 사용 중입니다.

터미널을 닫아도 백그라운드에서 Node.js 프로세스가 남아 있을 수 있습니다. 위에서 설명한 포트 점유 프로세스 확인 방법으로 PID를 찾아 종료하세요.

Q. 매번 포트가 충돌하는데 근본적인 해결 방법이 있나요?

package.json의 dev 스크립트에 고정 포트를 지정하거나, 프로젝트를 마칠 때 Ctrl+C로 서버를 반드시 종료하는 습관을 들이세요. .env.local에 PORT=3001처럼 별도 포트를 지정하는 방법도 있습니다.

Q. Create React App이나 Vite 프로젝트에서도 같은 방법이 적용되나요?

포트 충돌 확인, 방화벽 설정, 브라우저 캐시 삭제 등 기본적인 진단 방법은 동일합니다. 다만 포트 변경 옵션은 프레임워크마다 다릅니다. Vite는 기본 포트가 5173이고, CRA는 3000입니다.

localhost:3000이 안 열릴 때 해결 방법: 포트 충돌부터 방화벽까지 (2026)