npm run dev 포트 충돌 문제 해결법

 

 

Next.js 프로젝트를 개발할 때 npm run dev를 실행하면 기본적으로 포트 3000번에서 서버가 실행돼요. 그런데 가끔 이런 메시지를 본 적 있지 않나요?

 

⚠ Port 3000 is in use, trying 3001 instead.

 

이건 포트 3000을 이미 다른 프로세스가 사용하고 있어서 Next.js가 자동으로 포트 3001로 변경한 것을 의미해요. 문제없이 개발을 계속할 수 있지만, 특정 포트(예: 3000)를 유지해야 하는 상황이라면 이 문제를 해결해야겠죠?

 

그래서 포트 충돌을 해결하는 방법을 정리해 봤어요! 🔧

 

 

 

 

1. 포트 3000을 사용하는 프로세스 확인 후 종료하기

가장 확실한 방법은 포트 3000을 점유한 프로세스를 찾아 종료하는 것이에요.

운영체제	포트 점유 프로세스 확인 명령어	프로세스 종료 명령어
Windows	`netstat -ano	findstr :3000`
macOS/Linux	lsof -i :3000 또는 `sudo netstat -tulpn	grep 3000`

예제 (Windows 기준):

netstat -ano | findstr :3000
# 결과에서 PID 확인 후
taskkill /F /PID 12345

예제 (macOS/Linux 기준):

lsof -i :3000
# 결과에서 PID 확인 후
kill -9 12345

PID(프로세스 ID)를 제대로 입력해야 해요! 혹시 중요한 프로세스를 종료하면 시스템에 문제가 생길 수도 있으니 주의하세요. 🚨

 

 

 

 

2. Next.js가 자동으로 다른 포트를 사용하도록 설정하기

Next.js는 자동으로 포트 3001 같은 다른 포트를 사용하지만, 원하는 포트를 직접 지정할 수도 있어요.

(1) .env.local 파일에서 포트 변경

Next.js 프로젝트 루트 디렉토리에 .env.local 파일을 만들고 다음 내용을 추가하면 돼요.

PORT=4000

이제 npm run dev를 실행하면 포트 4000에서 서버가 실행돼요. 🎯

(2) 실행 명령어에서 직접 포트 지정

npm run dev -- -p 4000

이렇게 하면 Next.js 개발 서버가 4000번 포트에서 실행돼요.

 

 

 

 

3. 기존 Next.js 개발 서버 종료 후 다시 실행하기

때로는 기존 서버가 백그라운드에서 계속 실행 중이라 충돌이 발생할 수도 있어요.

해결 방법:

1. 실행 중인 터미널에서 Ctrl + C를 눌러 현재 실행 중인 서버를 종료해요.
2. 다시 npm run dev를 실행해요.

이렇게 하면 이미 실행 중인 서버를 완전히 종료한 후 다시 시작할 수 있어요. 👏

 

 

 

 

4. 컴퓨터 재부팅하기 (궁극의 해결책 🤣)

모든 방법이 실패한다면? 컴퓨터를 재부팅하세요!

때때로 포트를 점유한 프로세스가 비정상적으로 종료되지 않고 남아있는 경우가 있어요. 이런 경우, 시스템을 재부팅하면 문제 해결될 가능성이 커요.

 

 

 

5. 브라우저 캐시 정리하기

포트를 변경했는데도 웹페이지가 이상하게 뜬다면? 브라우저 캐시 문제일 가능성이 커요.

캐시를 지우는 방법은:

• Chrome: Ctrl + Shift + R 또는 Cmd + Shift + R (강력 새로고침)
• 설정 → 방문 기록 → 캐시 삭제

이렇게 하면 포트 변경 후에도 웹페이지가 정상적으로 뜰 가능성이 높아요.

 

 

 

✅ 어떤 방법을 선택해야 할까?

상황	추천 해결법
단순히 다른 포트를 사용해도 된다면	그냥 3001을 사용하면 됨 (아무 조치 필요 없음)
특정 포트(3000)를 꼭 사용해야 한다면	.env.local 파일에 PORT=3000 추가 또는 실행 시 npm run dev -- -p 3000 사용
포트 3000을 차지하는 프로세스를 종료하고 싶다면	netstat 또는 lsof 명령어로 확인 후 taskkill 또는 kill -9 실행
모든 방법이 안 된다면	컴퓨터 재부팅 🖥️

 

 

 

 

🔥 마무리

Next.js에서 npm run dev 실행 시 포트 3000 충돌 문제를 해결하는 다양한 방법을 알아봤어요! 포트 충돌이 자주 발생하는 환경이라면 .env.local에서 미리 포트를 지정하거나, 기존 서버를 제대로 종료하는 습관을 들이는 게 좋아요.

다음에 또 포트 문제가 생기면 이 글을 참고해서 차근차근 해결해보세요! 🚀