Spring Boot에서 spring.config.location으로 외부 설정을 지정한 뒤 기본 설정 파일이 로드되지 않는다면, 기본 검색 위치를 대체한 것이 원인일 수 있습니다. JAR 안의 application.properties를 유지하면서 외부 설정을 추가하려는 목적이라면 기존 location 지정을 제거하고 spring.config.additional-location으로 바꾸세요.
왜 외부 파일에 없는 기본값까지 사라질까?
spring.config.location은 기본 검색 위치에 경로를 더하는 옵션이 아닙니다. 설정 파일을 찾을 위치 자체를 지정한 목록으로 바꿉니다. 따라서 외부 파일에 없는 키를 JAR 안의 기본 파일에서 가져올 것이라고 기대하면, 필요한 값이 누락될 수 있습니다.
기본 검색 대상에는 클래스패스 루트와 클래스패스의 /config, 현재 작업 디렉터리와 그 아래 config/, 그리고 config/의 바로 아래 하위 디렉터리들이 포함됩니다. location으로 다른 위치를 지정하면 이 기본 목록이 유지되지 않습니다.
| 설정 | 검색 위치의 의미 | 선택할 상황 |
|---|---|---|
spring.config.location |
기본 검색 위치를 지정한 위치로 대체 | 설정 파일의 검색 범위를 직접 통제할 때 |
spring.config.additional-location |
기본 검색 위치를 유지하고 위치를 추가 | 공통 기본값 위에 환경별 값을 덮어쓸 때 |
additional-location에서 읽은 값은 기본 위치에서 읽은 같은 키의 값을 덮어쓸 수 있습니다. 다만 환경변수나 명령행 인자 등 다른 설정 소스까지 제거하거나 무조건 이기는 것은 아닙니다.
실행 설정과 경로를 순서대로 확인하기
-
실제 실행 명령, JVM 시스템 속성, 배포 환경변수에서
spring.config.location이 지정되어 있는지 확인합니다. 환경변수 이름은SPRING_CONFIG_LOCATION입니다. 기본값을 유지할 목적이라면 기존 지정을 제거하고 additional-location으로 전환합니다. -
추가할 대상이 디렉터리인지 파일인지 확인합니다. 디렉터리는
file:./runtime-config/처럼 끝에/를 붙입니다. 이 경우 기본 이름인 application을 기준으로 파일을 찾으며,spring.config.name을 변경했다면 그 이름을 사용합니다. 파일은file:./runtime-config/override.properties처럼 직접 지정할 수 있습니다. -
상대 경로의 기준을 확인합니다.
file:./runtime-config/는 프로세스의 현재 작업 디렉터리를 기준으로 해석합니다. JAR이 저장된 디렉터리와 작업 디렉터리가 같다고 가정하지 마세요. -
기본 파일에만 있는 키와 두 파일에 모두 있는 키를 각각 확인합니다. 전자가 유지되고 후자가 외부 값으로 바뀌면 의도한 조합입니다. 같은 키만 확인하면 기본 파일이 검색 대상에서 빠졌는지, 읽혔지만 덮어써졌는지 구분하기 어렵습니다.
spring.config.location과 spring.config.additional-location은 설정 파일의 검색 대상을 결정하는 초기 단계에 사용됩니다. 읽히기를 기대하는 application.properties 안에 넣어 해결하려 하지 말고, 명령행 인자·시스템 속성·환경변수로 전달하세요.
예제: JAR의 기본값을 유지하고 외부 값만 덮어쓰기
실행 가능한 Spring Boot JAR과 이를 실행할 Java 환경이 준비되어 있다고 가정합니다. JAR의 클래스패스 루트에 다음 application.properties를 포함합니다.
demo.label=base
demo.batch-size=20실행할 작업 디렉터리 아래에 runtime-config/를 만들고, 그 안의 application.properties에는 변경할 값만 둡니다.
demo.label=external예제를 단순하게 비교하려면 별도의 프로파일 설정 파일과 다른 기본 위치의 설정 파일이 없고, 환경변수·시스템 속성·명령행 인자에서도 demo 값을 지정하지 않아야 합니다. 명령행 속성 처리는 기본 동작을 사용한다고 가정합니다.
기본 위치가 빠지는 실행 방식
java -jar app.jar --spring.config.location=file:./runtime-config/이 경우 설정 파일 검색 위치는 지정한 외부 디렉터리로 바뀝니다. demo.label은 external이지만, JAR 내부 파일에만 둔 demo.batch-size는 그 파일에서 공급되지 않습니다. 이 누락이 시작 실패로 이어지는지는 애플리케이션이 해당 값을 요구하는 방식에 따라 달라집니다.
기본 위치를 유지하는 실행 방식
java -jar app.jar --spring.config.additional-location=file:./runtime-config/기존 location 인자를 위 인자로 교체하면 기본 검색 위치와 외부 디렉터리를 함께 사용합니다. Spring의 Environment에서 조회할 때 기대되는 값은 다음과 같습니다. 명령 자체가 이 표를 콘솔에 출력하는 것은 아닙니다.
| 키 | 기대 값 | 해석 |
|---|---|---|
demo.label |
external |
외부 파일이 기본 파일의 같은 키를 덮어씀 |
demo.batch-size |
20 |
외부 파일에 없는 키는 기본 파일의 값을 유지 |
바꾼 뒤에도 예상과 다를 때의 확인 사항
-
외부 위치가 없는 경우: 지정한 설정 위치가 없으면 기본적으로
ConfigDataLocationNotFoundException으로 시작이 실패합니다. 없어도 되는 위치에만optional:file:./runtime-config/처럼 optional 접두사를 사용하세요. 필수 외부 설정에 optional을 붙이면 경로 누락을 알아채기 어려워집니다. -
값이 계속 다른 경우: 환경변수, JVM 시스템 속성, 명령행 인자에서 같은 키를 지정했는지 확인합니다. 기본 명령행 처리에서는 명령행 속성이 파일 기반 값보다 우선합니다.
-
프로파일을 사용하는 경우: 지정한 파일·디렉터리 위치에서도 프로파일별 파일을 확인합니다. 활성 프로파일과 해당 파일의 값을 함께 확인해야 하며, 여러 위치와 프로파일을 조합한 우선순위는 위의 단순 예제만으로 판단하면 안 됩니다.
-
값의 출처를 확인해야 하는 경우: Actuator가 준비되어 있고 접근이 허용·노출된 환경에서는 env와 configprops 엔드포인트가 진단에 도움이 됩니다. 값은 마스킹될 수 있으므로 확인을 위해 민감한 설정을 공개하지 않도록 주의합니다.
수정 후에는 기본 파일 전용 키 하나와 외부에서 덮어쓴 키 하나를 함께 확인하세요. 두 값의 출처를 구분하면 기본값 유지와 외부 설정 적용을 한 번에 검증할 수 있습니다.