카테고리 없음

Spring Boot 포트 충돌 에러 해결법 총정리

트티 2025. 4. 2. 07:00

Spring Boot 포트 충돌 에러 해결법 총정리

📌 Spring Boot 실행 시 '포트 충돌'이란?

Spring Boot 애플리케이션을 실행할 때 "Port already in use" 또는 "Address already in use" 에러를 본 적 있으신가요? 이는 기본 포트인 8080이 이미 다른 프로세스에 의해 사용 중일 때 발생하는 일반적인 오류입니다.

🧭 목차

1. 포트 충돌의 원인

Spring Boot는 기본적으로 8080 포트를 사용합니다. 그러나 같은 포트를 사용하는 다른 서버나 백그라운드 프로세스가 이미 실행 중이라면, 새롭게 실행된 애플리케이션은 해당 포트를 사용할 수 없어 오류가 발생합니다. 이 경우 다음과 같은 상황일 수 있어요:

  • 이미 실행 중인 Spring Boot 애플리케이션이 있음
  • 로컬에서 Tomcat, Jenkins 등의 다른 서버가 8080 포트를 점유 중
  • 다른 개발 툴 또는 데몬 프로세스가 백그라운드에서 동작 중

이러한 문제를 해결하기 위해 가장 먼저 시도할 수 있는 방법은 Spring Boot의 포트를 변경하는 것입니다. 다음 단계에서는 구체적인 설정 방법을 살펴보겠습니다.

2. 포트를 변경하는 방법

Spring Boot에서 포트를 변경하는 가장 간단한 방법은 application.properties 또는 application.yml 파일을 수정하는 것입니다.

✅ application.properties 사용 시

server.port=8081

위와 같이 설정하면 애플리케이션이 8081 포트에서 실행되며 기존 충돌을 피할 수 있어요.

✅ application.yml 사용 시

server:
  port: 8081

개발 중에는 원하는 임의의 포트로 지정하여 테스트 환경을 안정적으로 유지할 수 있습니다.

💡 명령줄에서 일시적으로 포트 변경

별도의 설정 파일을 수정하지 않고 실행 시점에 포트를 임시로 변경할 수도 있어요:

./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8082

이 방식은 빠르게 테스트하거나 여러 인스턴스를 실행할 때 유용합니다.

3. 포트를 사용 중인 프로세스 확인 및 종료

포트 충돌이 발생했다면 어떤 프로세스가 해당 포트를 사용하고 있는지 먼저 확인해야 합니다. 운영 체제에 따라 다음 명령어를 사용할 수 있어요.

🔍 Mac/Linux: 포트 8080 사용 중인 프로세스 찾기

lsof -i :8080

결과에서 PID 값을 확인하고, 해당 프로세스를 종료할 수 있습니다.

kill -9 [PID]

🔍 Windows: 포트 사용 확인

netstat -ano | findstr :8080

PID를 확인한 후 작업 관리자(Task Manager)에서 프로세스를 찾아 종료하거나, 다음 명령어를 사용할 수 있어요:

taskkill /PID [PID] /F

이처럼 포트를 사용 중인 프로세스를 종료하거나, 포트 번호를 변경하는 방식으로 충돌 문제를 해결할 수 있습니다.

이제 포트를 조정하거나 프로세스를 종료하여 충돌 문제를 해결했다면, 그 외 자주 묻는 질문들과 실무 팁을 살펴보는 것이 좋습니다. 다음 섹션에서 함께 알아볼게요.

4. 자주 묻는 질문과 실무 팁

❓ Q1. 매번 포트를 바꾸는 게 번거로운데 자동화할 수 없나요?

네, 가능합니다. 개발 환경에서는 포트를 매번 수동으로 지정하는 대신, application-dev.properties 파일을 활용하여 프로파일별로 포트를 분리해두는 방법이 있어요.

# application-dev.properties
server.port=8083

그리고 실행 시 다음처럼 dev 프로파일을 지정하면 됩니다:

--spring.profiles.active=dev

❓ Q2. 여러 개의 Spring Boot 애플리케이션을 동시에 실행하려면?

각 애플리케이션에 고유한 포트를 할당하면 동시에 실행할 수 있어요. 예를 들어 8081, 8082, 8083 등으로 포트를 나눠 실행하면 충돌 없이 테스트 가능합니다.

🧠 실무 꿀팁: 포트 자동화 스크립트 사용하기

Shell Script나 배치 파일을 이용해 실행 시 자동으로 포트를 지정하는 방법도 있습니다. 예를 들어, 랜덤 포트를 할당하는 스크립트를 만들어 테스트 자동화를 구성할 수 있어요:

#!/bin/bash
PORT=$(( ( RANDOM % 1000 )  + 8000 ))
./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=$PORT

📈 향후 예측: Spring Boot의 포트 유연성 강화

Spring Boot는 앞으로 더 유연한 포트 매핑과 컨테이너 기반의 실행을 기본으로 할 가능성이 높습니다. 예를 들어 Docker 컨테이너 내에서 실행되면, 외부 포트와 내부 포트를 매핑하는 구조가 일반화될 것으로 보입니다:

docker run -p 8080:8080 my-spring-app

따라서 포트 충돌은 향후 점점 드물어질 수 있지만, 개발 초기에는 여전히 발생할 수 있기 때문에 포트 관련 설정에 익숙해지는 것이 중요해요.

마지막으로 이번 글을 정리하고, 주요 키워드를 태그로 정리해볼게요.

🧩 결론

Spring Boot 포트 충돌은 초보 개발자뿐 아니라 숙련된 개발자에게도 빈번히 발생하는 문제입니다. 하지만 원인을 정확히 파악하고, 적절한 대응 방법을 익혀두면 단 몇 초 만에 해결할 수 있어요.

가장 중요한 것은 현재 어떤 포트가 사용 중인지 파악하는 능력과 포트를 유연하게 설정할 수 있는 습관</strong입니다. 더불어 프로파일 기반 설정, 명령줄 실행, 자동화 스크립트 등 다양한 방법을 숙지해두면 실무에서 생산성을 더욱 높일 수 있어요.

📘 Spring Boot 공식 문서 보러가기

🏷️ 태그

Spring Boot, 포트 충돌, 포트 변경, 서버 설정, 개발자 팁, 서버 오류, application.properties, 서버 포트 변경