npm run dev 시 EACCES: Permission Denied 포트 충돌 해결방법

npm run dev 실행 시 다음 오류가 발생할 때가 있습니다:

?!

Error: listen EACCES: permission denied 0.0.0.0:3000

원인

이 오류는 Windows NAT 서비스가 포트 3000번을 점유하고 있을 때 발생합니다. Docker Desktop이나 WSL2를 사용하는 환경에서 자주 나타나는 현상입니다.

해결 방법

관리자 권한으로 명령 프롬프트를 열고 다음 명령어를 순서대로 실행합니다:

net stop winnat
net start winnat

첫 번째 명령어는 NAT 서비스를 중지시켜 점유된 포트를 해제하고, 두 번째 명령어는 서비스를 다시 시작합니다. 이 과정에서 포트 충돌이 해결됩니다.

Oh Oh

추가 팁

문제가 지속되면 다른 포트를 사용해보세요:

npm run dev -- -p 3001

또는 어떤 프로세스가 포트를 사용하는지 확인하려면:

netstat -ano | findstr :3000

이 간단한 방법으로 대부분의 EACCES 포트 오류를 해결할 수 있습니다.

상세한 원리와 배경 지식

EACCES 오류의 정체

EACCES는 "Error Access"의 줄임말로, 시스템이 특정 리소스에 대한 접근을 거부했을 때 발생합니다. 여기서 0.0.0.0:3000에 주목해야 합니다. 0.0.0.0은 모든 네트워크 인터페이스를 의미하는 특별한 IP 주소입니다. 즉, 개발 서버가 localhost뿐만 아니라 네트워크에 연결된 모든 인터페이스에서 들어오는 요청을 받을 수 있도록 설정되어 있다는 뜻입니다.

Windows NAT 서비스의 역할

Windows NAT 서비스(winnat)는 Network Address Translation을 담당하는 시스템 서비스입니다. 이 서비스는 가상 머신이나 컨테이너 환경에서 네트워크 주소 변환을 처리합니다. Docker Desktop, Hyper-V, WSL2 등을 사용할 때 자동으로 활성화되며, 이 과정에서 여러 포트들을 예약하거나 점유하게 됩니다.

문제는 이 NAT 서비스가 포트 3000번을 비롯한 여러 포트들을 시스템 레벨에서 점유하는 경우가 있다는 것입니다. 이런 상황에서 개발 서버가 같은 포트를 사용하려고 시도하면, 운영체제는 이미 해당 포트가 점유되어 있다고 판단하고 접근을 거부합니다.

해결 방법이 효과적인 이유

net stop winnat과 net start winnat 명령어가 효과적인 이유는 Windows 서비스의 동작 방식에 있습니다. 서비스가 중지되면 해당 서비스가 점유하고 있던 모든 네트워크 리소스가 해제됩니다. 이는 마치 프로그램을 종료했을 때 사용하던 메모리가 해제되는 것과 같은 원리입니다.

서비스가 재시작되면 필요한 리소스만 다시 할당하게 되는데, 이 과정에서 이전에 발생했던 포트 충돌이나 예약 상태 등의 문제가 해결됩니다. 이는 컴퓨터를 재부팅하는 것과 비슷한 효과이지만, 전체 시스템을 재시작하지 않고도 특정 서비스만 초기화할 수 있다는 장점이 있습니다.

포트 충돌 진단하기

포트 충돌 문제를 더 깊이 이해하고 진단하려면 netstat 명령어를 활용할 수 있습니다. netstat -ano | findstr :3000 명령어는 현재 포트 3000번을 사용하는 모든 프로세스를 보여줍니다. 결과에서 나타나는 PID를 통해 작업 관리자에서 해당 프로세스를 찾아 확인할 수 있습니다.

또한 netstat -rn 명령어로 라우팅 테이블을 확인하거나, ipconfig /all 명령어로 네트워크 어댑터 정보를 살펴보는 것도 네트워크 관련 문제를 진단하는 데 도움이 됩니다.

개발 환경 최적화 방안

이런 문제를 예방하기 위해서는 개발 환경을 적절히 설정하는 것이 중요합니다. Docker Desktop을 사용하는 경우, 설정에서 사용하지 않는 기능들을 비활성화하면 불필요한 포트 점유를 줄일 수 있습니다. WSL2를 사용한다면 .wslconfig 파일을 통해 메모리나 네트워크 설정을 조정할 수 있습니다.

또한 개발 프로젝트마다 다른 포트를 사용하도록 설정하는 것도 좋은 방법입니다. 예를 들어, Next.js 프로젝트는 3000번, React 프로젝트는 3001번, Express 서버는 3002번 등으로 구분하여 사용하면 포트 충돌을 미연에 방지할 수 있습니다.

이 문제를 통해 얻는 교훈

이 경험을 통해 우리는 개발 환경에서 발생하는 문제들이 항상 코드 자체의 문제만은 아니라는 것을 배울 수 있습니다. 때로는 시스템 레벨의 이해가 필요하고, 운영체제와 개발 도구들 사이의 상호작용을 파악하는 것이 중요합니다.

오류 메시지를 그대로 받아들이지 않고, 그 배경과 맥락을 이해하려고 노력하는 것이 더 나은 개발자가 되는 길입니다. 이런 문제 해결 과정에서 네트워크, 운영체제, 시스템 서비스 등에 대한 지식이 자연스럽게 쌓이게 됩니다.