Node.js에서 ‘Error: listen EADDRINUSE’ 에러 해결법

🚨 도입부

여러분이 Node.js 애플리케이션을 개발하다가 “Error: listen EADDRINUSE”라는 에러 메시지를 만났을 때의 좌절감을 상상해 보세요. 이 에러는 특히 서버를 시작하려고 할 때 자주 발생하며, 이미 사용 중인 포트를 다시 사용하려고 시도할 때 나타납니다. 이러한 상황은 특정 포트가 남아 있다고 믿었는데 그렇지 않을 때, 다른 프로세스가 이미 해당 포트를 점유하고 있을 때, 또는 애플리케이션을 잘못 종료하고 다시 시작할 때 발생할 수 있습니다.

이 글에서는 이 에러를 해결하기 위한 다양한 방법을 살펴보겠습니다. 예상 해결 시간은 약 5분에서 30분 정도이며, 난이도는 초보자부터 중급 개발자 수준입니다. 각 방법은 구체적인 코드 예제와 함께 제공되므로 따라 하기 쉽습니다.

🔍 에러 메시지 상세 분석

“Error: listen EADDRINUSE”는 Node.js에서 매우 흔한 에러로, 특히 서버 애플리케이션을 개발할 때 자주 마주칩니다. 이 에러는 기본적으로 포트 충돌을 의미하며, ‘EADDRINUSE’는 ‘Address in use’, 즉 해당 주소(포트)가 이미 사용 중임을 나타냅니다.

• 에러 발생 상황 1: 서버를 재시작할 때, 이전 프로세스가 완전히 종료되지 않아 포트가 여전히 점유된 경우
• 에러 발생 상황 2: 동일한 포트를 사용하는 다른 애플리케이션이 이미 실행 중인 경우
• 에러 발생 상황 3: 애플리케이션이 비정상적으로 종료된 후 포트가 해제되지 않은 경우
• 에러 발생 상황 4: 개발 환경에서 여러 인스턴스를 동시에 실행하려고 할 때
• 에러 발생 상황 5: 잘못된 포트 설정으로 인해 충돌이 발생하는 경우

이 에러는 초보자가 이해하기 어려울 수 있지만, 메시지 자체는 문제가 발생한 이유를 명확히 설명합니다. ‘listen’은 서버가 클라이언트 요청을 수신하기 위해 대기 중임을, ‘EADDRINUSE’는 사용 중인 포트를 의미합니다. 비슷한 에러로는 ‘ECONNREFUSED'(연결 거부), ‘ECONNRESET'(연결 재설정) 등이 있으며, 이들은 네트워크 연결 문제와 관련이 있습니다.

🧐 발생 원인 분석

이 에러의 주요 원인은 다양합니다. 각 원인과 시나리오를 살펴보겠습니다:

1. 프로세스 미종료: 종종 개발자가 서버를 종료하지 않고 다시 시작하려 할 때 포트가 이미 점유되어 있을 수 있습니다. 예를 들어, Ctrl + C로 종료하지 않고 창을 닫아버린 경우입니다.
2. 다른 애플리케이션과의 충돌: 같은 포트를 사용하는 다른 애플리케이션이 실행 중일 수 있습니다. 예를 들어, 포트 3000을 사용하는 두 개의 다른 서버를 동시에 실행하려고 할 때입니다.
3. 비정상 종료 후 잔류 프로세스: 서버가 비정상적으로 종료되면, 포트가 여전히 사용 중으로 표시될 수 있습니다.
4. 개발 환경 설정 오류: 잘못된 설정 파일로 인해 포트가 충돌할 수 있습니다. 예를 들어, 여러 개발자가 같은 설정을 공유할 때 발생할 수 있습니다.
5. 네트워크 설정 문제: 네트워크 또는 방화벽 설정 문제로 인해 포트가 사용 중으로 표시될 수 있습니다.

각 원인은 고유한 상황과 환경에 따라 다르게 나타날 수 있으며, 운영 체제별로도 차이가 발생할 수 있습니다. 예를 들어, Windows에서는 프로세스가 종료되지 않는 경우가 많고, Unix 계열에서는 포트를 강제로 해제할 수 있는 도구가 조금 더 다양합니다.

✅ 해결 방법

다양한 해결 방법을 단계별로 살펴보겠습니다.

즉시 해결: 1분 내 적용 가능한 빠른 방법

• 포트 상태 확인 및 프로세스 종료: 포트를 사용 중인 프로세스를 찾고 종료합니다. Windows에서는 netstat -ano | findstr :3000을 사용하고, Unix 계열에서는 lsof -i :3000을 사용합니다.

// Windows에서 포트 확인 및 종료
// 명령 프롬프트에서 실행
netstat -ano | findstr :3000
// 프로세스 ID를 얻은 후
Taskkill /PID  /F

• 서버 재시작: 프로세스를 강제로 종료한 후 서버를 재시작합니다. Ctrl + C로 서버를 안전하게 종료하고 다시 시작하세요.
• 포트 변경: 충돌을 피하기 위해 다른 포트를 사용합니다. 애플리케이션 설정 파일에서 포트를 변경하세요.

// 서버 설정 파일에서 포트 변경
const port = process.env.PORT || 3001;
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

표준 해결: 일반적이고 안전한 해결법

• 포트 사용 상황 점검: 정기적으로 포트 사용 상태를 점검하여 충돌을 방지합니다.
• 환경 변수 사용: 포트를 환경 변수로 설정하여 유연성을 높입니다.

// 환경 변수를 사용하여 포트 설정
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

• 프로세스 매니저 사용: PM2와 같은 프로세스 매니저를 사용하여 프로세스를 관리하고 충돌을 방지합니다.
• 포트 해제 스크립트 작성: 서버 종료 시 포트를 해제하는 스크립트를 작성합니다.

// 프로세스 종료 시 포트를 해제하는 스크립트
process.on('SIGTERM', () => {
  server.close(() => {
    console.log('Process terminated');
  });
});

• 개발 환경과 운영 환경의 분리: 개발 환경과 운영 환경에서 사용되는 포트를 분리하여 충돌을 방지합니다.

고급 해결: 복잡한 상황을 위한 해결법

• 포트 점유 상태 자동 확인: 서버 시작 전에 포트 점유 상태를 자동으로 확인하는 스크립트를 작성합니다.
• 네트워크 및 방화벽 설정 점검: 네트워크와 방화벽 설정을 점검하여 비정상적인 포트 점유를 방지합니다.
• 포트 재사용 옵션 설정: Node.js 서버에서 포트 재사용 옵션을 활성화합니다.

// 포트 재사용 옵션 설정
const server = require('http').createServer(app);
server.listen(port, '0.0.0.0', () => {
  console.log(`Server running on port ${port}`);
});
server.on('listening', () => {
  console.log('Server is ready');
});

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하기 위한 방법들을 소개합니다.

• 코드 리뷰 및 표준화: 코드를 주기적으로 리뷰하여 포트 충돌을 방지합니다.
• 포트 관리 정책 수립: 팀 내에서 포트 사용 정책을 수립하고 공유합니다.
• 자동화 도구 사용: CI/CD 파이프라인에 포트 점검 도구를 추가합니다.
• 환경 구성 파일 관리: 환경 구성 파일을 철저히 관리하여 오류를 방지합니다.

🎯 마무리 및 추가 팁

이제 ‘Error: listen EADDRINUSE’ 에러를 해결할 수 있는 방법을 알게 되셨습니다. 핵심은 포트 충돌을 이해하고 적절히 관리하는 것입니다. 비슷한 에러로는 ‘ECONNREFUSED’와 ‘ECONNRESET’가 있으며, 이들에 대한 해결책도 추후 다루겠습니다. 더 나은 개발자가 되기 위한 여정에 이 글이 도움이 되었기를 바랍니다. 항상 코드를 꼼꼼히 점검하고, 문제를 마주했을 때는 차근차근 해결해 나가세요!