Node.js 서버를 실행하려는데 'Error: listen EADDRINUSE :::8080' 메시지가 출력되며 실행이 거부되는 경우가 있습니다. 이는 해당 포트를 이미 다른 프로세스가 점유하고 있기 때문입니다. 실제로는 아무것도 실행하지 않은 것처럼 보여도, 백그라운드에서 좀비 프로세스나 이전 세션이 포트를 물고 있는 경우가 대부분입니다. 이 글에서는 Windows와 Linux 환경 모두에서 포트 충돌을 진단하고 해결하는 실전 명령어와 주의사항을 정리합니다.
 |
| Node.js EADDRINUSE 에러 해결 완벽 가이드 netstat과 lsof 실전 활용법 |
1. Windows 환경: netstat + taskkill로 포트 점유 프로세스 제거
Windows에서는 netstat 명령어로 포트 사용 현황을 확인하고, taskkill로 해당 프로세스를 강제 종료할 수 있습니다.
1-1. 관리자 권한으로 CMD 또는 PowerShell 실행
포트 확인 및 프로세스 종료 명령은 관리자 권한이 필요합니다. 시작 메뉴에서 'cmd' 또는 'PowerShell'을 검색한 뒤 관리자 권한으로 실행하십시오.
1-2. 포트 사용 중인 프로세스 확인
- 전체 포트 목록 확인:
netstat -ano - 특정 포트만 필터링:
netstat -ano | findstr 8080
출력 결과의 맨 오른쪽 열이 PID(프로세스 ID)입니다. 예를 들어 8080 포트를 사용 중인 PID가 13340이라면, 이 프로세스를 종료해야 합니다.
1-3. netstat 주요 옵션 정리
- -a: 모든 활성 TCP 연결 및 수신 대기 중인 TCP/UDP 포트 표시
- -n: 호스트명 대신 IP 주소와 포트 번호로 표시 (속도 향상)
- -o: 각 연결의 PID 포함
- -p: 특정 프로토콜(TCP, UDP 등)만 필터링
- -s: 프로토콜별 통계 표시
- -r: 라우팅 테이블 출력 (route print와 동일)
Tip: 출력이 너무 길면 Ctrl+C로 중단하고, findstr로 필터링하는 것을 권장합니다.
1-4. PID로 프로세스 강제 종료
확인한 PID를 이용해 프로세스를 종료합니다.
- 명령어:
taskkill /f /pid 13340 - /f: 강제 종료 옵션
- /pid: 종료할 프로세스 ID 지정
종료 후 브라우저에서 localhost:8080에 접속이 불가능하면 정상적으로 포트가 해제된 것입니다. 작업 관리자의 '세부 정보' 탭에서 PID를 확인하여 어떤 프로그램인지 사전에 파악하는 것을 권장합니다.
2. Linux/macOS 환경: lsof로 포트 점유 프로세스 추적
Linux와 macOS에서는 lsof(List Open Files) 명령어를 사용하여 포트를 점유한 프로세스를 정확하게 추적할 수 있습니다.
2-1. lsof 설치
- Debian/Ubuntu:
sudo apt install lsof - RHEL/CentOS:
sudo yum install lsof - Fedora:
sudo dnf install lsof - macOS: 기본 설치되어 있음
2-2. 특정 포트 사용 프로세스 확인
8080 포트를 사용 중인 프로세스를 찾으려면 다음 명령어를 실행합니다.
sudo lsof -i :8080
출력 결과에서 PID 열을 확인하면 해당 프로세스를 식별할 수 있습니다.
2-3. lsof 주요 옵션 및 활용 예시
- lsof +D /path/to/directory: 특정 디렉토리 내에서 열려 있는 파일과 프로세스 확인
- lsof -p 1234: PID 1234가 연 모든 파일 확인
- sudo lsof -i: 모든 네트워크 소켓(포트) 표시
- sudo lsof -i :5555: 특정 포트 사용 프로세스 확인
- watch -n 2 'lsof +D /var/log': 2초마다 결과 업데이트 (실시간 모니터링)
- lsof -d 0: 특정 파일 디스크립터(FD) 기준 출력
2-4. lsof 출력 필드 해석
- COMMAND: 프로세스 이름
- PID: 프로세스 ID
- USER: 실행 사용자
- FD: File Descriptor (cwd: 현재 작업 디렉토리, txt: 프로그램 텍스트, mem: 메모리 매핑 파일)
- TYPE: 파일 종류 (DIR: 디렉토리, REG: 일반 파일, CHR: 문자 장치, unix: 유닉스 도메인 소켓)
- DEVICE: 장치 번호
- SIZE/OFF: 파일 크기 또는 오프셋
- NODE: 노드 번호 (inode)
- NAME: 파일명 또는 소켓 주소
주의: 네트워크 소켓도 파일로 취급되므로, lsof로 포트 점유 상황을 추적할 수 있습니다. unix 타입 소켓은 로컬 프로세스 간 통신(IPC)에 사용되며, 성능이 TCP 소켓보다 빠릅니다.
2-5. 프로세스 종료
PID를 확인한 뒤 프로세스를 종료합니다.
- Graceful 종료:
kill 1234 - 강제 종료 (최후 수단):
kill -9 1234
권장 사항: 가능하면 kill 명령으로 정상 종료를 시도하고, 응답이 없을 때만 kill -9를 사용하십시오. 강제 종료는 데이터 손실이나 리소스 누수를 유발할 수 있습니다.
3. 포트를 종료하지 않고 변경하는 방법
프로세스를 종료하지 않고 애플리케이션의 포트 설정을 변경하여 충돌을 회피할 수도 있습니다.
3-1. Node.js 애플리케이션
코드에서 포트를 환경 변수로 받도록 수정합니다.
const PORT = process.env.PORT || 3001;- 실행 시:
PORT=3001 node app.js
3-2. Spring Boot 애플리케이션
application.properties 또는 application.yml 파일에 포트를 명시합니다.
server.port=8081
3-3. Docker 컨테이너
포트 매핑을 변경하여 호스트 포트와 컨테이너 포트를 분리합니다.
docker run -p 8081:8080 myapp
Tip: 개발 환경에서는 포트 변경이 더 안전하고 빠릅니다. 운영 환경에서는 점유 프로세스를 정확히 파악한 뒤 종료하는 것을 권장합니다.
4. 실전 트러블슈팅 시나리오 및 주의사항
4-1. 좀비 프로세스가 포트를 점유하는 경우
개발 중 Ctrl+C로 Node.js 서버를 종료했지만, 백그라운드에서 프로세스가 살아있는 경우가 있습니다. 이 경우 netstat 또는 lsof로 PID를 확인하고 강제 종료하십시오.
4-2. 여러 Node.js 인스턴스가 동시 실행 중인 경우
PM2, nodemon 등 프로세스 매니저를 사용하는 경우, 동일 포트로 여러 인스턴스가 실행될 수 있습니다. pm2 list 또는 ps aux | grep node로 전체 프로세스를 확인하고, 불필요한 인스턴스를 정리하십시오.
4-3. 시스템 서비스가 포트를 점유하는 경우
일부 시스템 서비스(예: Apache, Nginx)가 기본 포트(80, 443)를 점유할 수 있습니다. 이 경우 서비스 중지 명령을 사용하십시오.
- Linux:
sudo systemctl stop nginx - Windows: 서비스 관리자에서 해당 서비스 중지
4-4. 방화벽 또는 보안 정책에 의한 차단
포트가 열려 있어도 방화벽 규칙에 의해 접근이 차단될 수 있습니다. telnet localhost 8080 또는 nc -zv localhost 8080으로 포트 연결 가능 여부를 테스트하십시오.
요약 및 Action Item
포트 충돌 해결은 1) 포트 사용 확인 → 2) PID 식별 → 3) 프로세스 종료 또는 포트 변경의 3단계로 진행됩니다. Windows는 netstat -ano | findstr 포트번호와 taskkill /f /pid를, Linux/macOS는 sudo lsof -i :포트번호와 kill을 사용하십시오. 당장 실행할 Action Item: 현재 개발 환경에서 자주 사용하는 포트(3000, 8080 등)를 netstat 또는 lsof로 확인하고, 점유 프로세스 목록을 스크립트로 저장해두십시오. 이렇게 하면 다음 충돌 시 진단 시간을 90% 이상 단축할 수 있습니다.
#함께 읽으면 좋은 글
PyInstaller로 파이썬 스크립트를 exe 실행 파일로 변환하는 완벽 가이드 : 바로보기
댓글
댓글 쓰기