Vite Dev Server 포트 충돌 문제 해결하기

증상 및 오류 메시지

Vite Dev Server를 실행할 때 다음과 같은 오류 메시지를 자주 마주하게 됩니다:

Error: Port 3000 is already in use.

이 오류는 Vite가 기본적으로 사용하는 포트인 3000번 포트가 이미 다른 프로세스에 의해 사용 중일 때 발생합니다. 이로 인해 개발 서버가 정상적으로 시작되지 않으며, 개발 환경에서 불편을 초래합니다.

원인

이 문제의 주된 원인은 두 가지입니다. 첫 번째는 다른 애플리케이션이 이미 3000번 포트를 사용 중인 경우입니다. 두 번째는 이전에 실행된 Vite Dev Server가 종료되지 않고 백그라운드에서 실행되고 있는 경우입니다. 이 경우, 해당 프로세스가 포트를 점유하고 있어 새로운 서버가 시작되지 못합니다.

확인 명령어

포트 충돌 여부를 확인하기 위해 다음과 같은 명령어를 사용할 수 있습니다. 이 명령어는 3000번 포트를 사용 중인 프로세스를 찾는 데 유용합니다.

Windows

netstat -ano | findstr :3000

macOS / Linux

lsof -i :3000

이 명령어를 실행하면 포트를 사용 중인 프로세스의 PID(Process ID)를 확인할 수 있습니다. 만약 해당 포트가 사용 중이라면, 다음 단계로 해당 프로세스를 종료해야 합니다.

해결 절차

포트 사용 중인 프로세스 확인: 위의 확인 명령어를 통해 3000번 포트를 사용 중인 프로세스를 확인합니다.
프로세스 종료: 확인된 PID를 사용하여 해당 프로세스를 종료합니다.
- Windows:
```
taskkill /PID <PID> /F
```
- macOS / Linux:
```
kill -9 <PID>
```
Vite Dev Server 재실행: 프로세스를 종료한 후, Vite Dev Server를 다시 실행합니다.
```
npm run dev
```
포트 변경 (선택 사항): 만약 포트 충돌이 자주 발생한다면, Vite의 설정 파일인 vite.config.js에서 포트를 변경할 수 있습니다.
```
export default {
  server: {
    port: 3001 // 원하는 포트 번호로 변경
  }
}
```

흔한 실수

프로세스 종료를 잊는 경우: 이전에 실행한 Vite Dev Server가 종료되지 않아 포트가 점유된 상태로 남아있을 수 있습니다. 이 경우, 반드시 프로세스를 종료한 후 다시 실행해야 합니다.
포트 변경 설정을 잊는 경우: 설정 파일에서 포트를 변경했음에도 불구하고, 이전 설정을 기억하고 계속 3000번 포트를 사용하려고 시도하는 경우가 있습니다. 이럴 땐 설정 파일을 다시 확인해야 합니다.

재발 방지 체크리스트

정기적으로 프로세스 상태 확인: 개발 환경에서 포트 사용 현황을 주기적으로 확인하여 불필요한 프로세스가 남아있지 않도록 합니다.
포트 변경 고려: 여러 프로젝트를 동시에 진행할 경우, 각 프로젝트의 포트를 다르게 설정하여 충돌을 방지합니다.
개발 서버 종료 습관화: 개발이 끝난 후에는 항상 서버를 종료하는 습관을 들입니다. 이렇게 하면 불필요한 포트 점유를 방지할 수 있습니다.

이러한 절차를 통해 Vite Dev Server의 포트 충돌 문제를 효과적으로 해결할 수 있습니다. 개발 환경에서의 원활한 작업을 위해 항상 포트 관리에 유의하시기 바랍니다.

실무 적용 체크리스트

vite dev server port already in use 해결을 적용하기 전에 현재 운영 환경의 기준값과 예외 상황을 먼저 정리합니다.
변경 전후로 확인할 지표를 정하고, 문제가 생겼을 때 되돌릴 수 있는 절차를 문서화합니다.
한 번에 모든 서버나 서비스에 적용하기보다 작은 범위에서 검증한 뒤 점진적으로 확대합니다.
담당자, 확인 시간, 장애 판단 기준을 명확히 남겨 같은 문제가 반복될 때 빠르게 대응할 수 있게 합니다.

참고한 자료

[# Spring Boot + Docker MySQL] Access denied for user ‘root’@‘localhost’ 해결 — 원인은 비밀번호가 아니라 포트 충돌이었다