Spring Boot의 기본 설정에서 같은 server.port를 설정 파일·OS 환경변수·명령행 인자에 모두 지정하면 명령행 인자의 값이 적용됩니다. 세 소스만 비교하면 우선순위는 명령행 인자 > OS 환경변수 > 설정 파일입니다.
설정 파일을 바꿔도 포트가 달라지지 않는 이유
Spring Boot는 여러 설정 소스를 Spring Environment에 모으고, 같은 속성이 겹치면 소스의 우선순위에 따라 값을 결정합니다. 파일을 마지막에 수정했다고 그 값이 우선하는 것은 아닙니다.
이 구조를 이용하면 파일에 공통 기본값을 두고 실행 환경마다 환경변수로 바꾸거나, 한 번의 실행에만 명령행 인자로 다른 값을 지정할 수 있습니다. 반면 파일만 읽어서는 실제 적용값을 알기 어려우므로 실행 조건도 함께 확인해야 합니다.
세 가지 표기를 같은 속성으로 비교하기
| 설정 소스 | 지정 예 | 세 소스 사이의 우선순위 |
|---|---|---|
| application.properties | server.port=8081 |
낮음 |
| OS 환경변수 | SERVER_PORT=8082 |
중간 |
| 명령행 인자 | --server.port=8083 |
높음 |
환경변수에서는 server.port에 대응하는 이름으로 SERVER_PORT를 사용합니다. 기본적으로 SpringApplication은 --로 시작하는 옵션 인자를 속성으로 변환하여 Environment에 추가합니다.
- 실행 인자에
--server.port가 있으면 그 값을 선택합니다. - 해당 인자가 없으면 실행 프로세스에 전달된
SERVER_PORT를 확인합니다. - 둘 다 없으면 로드된 설정 파일의
server.port를 확인합니다.
이 판단 순서는 다른 설정 소스가 같은 속성을 덮어쓰지 않는다는 전제에서 사용합니다.
예제: 8081·8082·8083 중 어떤 값이 적용되는가
Java로 실행 가능한 Spring Boot 웹 애플리케이션 app.jar가 준비되어 있고, 명령행 속성 처리를 비활성화하지 않았다고 가정합니다. 아래 실행 구문은 Bash 같은 유닉스 계열 셸 기준입니다. 다른 설정 파일이나 시스템 속성, 테스트 설정 등에서는 포트를 지정하지 않습니다.
먼저 JAR를 실행할 작업 디렉터리의 application.properties에 다음 값을 둡니다. 기본 설정 검색 위치를 변경하지 않았다면 현재 디렉터리의 이 파일은 로드 대상입니다.
server.port=8081이어서 환경변수와 명령행 인자를 함께 지정해 실행하는 예입니다.
SERVER_PORT=8082 java -jar app.jar --server.port=8083이 구문은 해당 Java 프로세스에 환경변수 SERVER_PORT=8082를 전달하고, 애플리케이션 인자로 --server.port=8083을 넘깁니다. 예상되는 최종 server.port 값은 8083입니다. 환경변수가 파일 값보다 우선하지만, 명령행 인자가 환경변수보다 다시 우선하기 때문입니다.
| 같은 파일을 두고 실행하는 구문 | 예상 server.port | 판단 이유 |
|---|---|---|
SERVER_PORT=8082 java -jar app.jar --server.port=8083 |
8083 | 명령행 인자 우선 |
SERVER_PORT=8082 java -jar app.jar |
8082 | 명령행 지정이 없어 환경변수 적용 |
java -jar app.jar |
8081 | SERVER_PORT도 전달되지 않았다면 파일 값 적용 |
마지막 행은 셸에 이미 설정된 SERVER_PORT도 없다는 전제입니다. 명령 앞에서 환경변수 지정을 생략하는 것만으로 기존 환경변수가 제거되지는 않습니다.
예상과 다를 때 확인할 조건과 적용 범위
- 명령행 속성 처리 여부: 애플리케이션에서
SpringApplication.setAddCommandLineProperties(false)를 호출했다면--server.port가 기본 방식으로 Environment에 추가되지 않습니다. - 프로세스에 전달된 환경변수: 설정을 편집한 셸과 실제 애플리케이션 실행 환경이 같은지 확인합니다. 비교 대상은 Java 프로세스가 전달받은
SERVER_PORT입니다. - 실제로 로드된 파일: 외부 파일과 프로파일별 파일 등 여러 설정 파일이 있으면 파일 사이에도 우선순위가 있습니다. 먼저 파일 계층에서 선택되는 값을 파악한 뒤 환경변수·명령행 인자와 비교합니다.
- 다른 설정 소스: Java 시스템 속성,
SPRING_APPLICATION_JSON, 테스트용 속성 등도 우선순위에 참여합니다. 세 소스의 비교표가 Spring Boot 전체 설정 순서를 뜻하지는 않습니다.
추가 진단이 필요하면 Actuator의 env와 configprops 엔드포인트가 속성의 출처나 바인딩 확인에 도움이 될 수 있습니다. 다만 사용 가능 여부와 노출 설정을 확인해야 하며, 값은 기본적으로 마스킹되므로 조회만으로 원래 값이 보인다고 가정하면 안 됩니다.
포트가 예상과 다르면 파일 수정부터 반복하기보다 실제 실행 인자와 프로세스 환경변수를 먼저 대조하세요. 선택된 값과 그 출처를 함께 기록하면 다음 실행에서도 같은 기준으로 판단할 수 있습니다.