Spring Boot 报 ConfigDataLocationNotFoundException

从 Spring Boot 2.4 开始，配置处理机制由旧版的 ConfigFileApplicationListener 全面重构为 ConfigDataEnvironmentPostProcessor。若通过命令行、环境变量或 spring.profiles.active 指定了不存在的配置文件，或者使用 spring.config.import 引入了缺失的资源且未声明 optional: 前缀，Spring Boot 启动时将严格校验并直接抛出 ConfigDataLocationNotFoundException。

Issue & Env（案发现场与环境）

在本地开发或 CI/CD 流水线中部署 Spring Boot 2.4+ / 3.x 应用时，指定环境 profile 或加载外部化挂载文件常遭遇容器无法拉起的问题：

• 受影响版本：Spring Boot 2.4.0 ~ 3.3.x（引入 ConfigData 机制后的所有版本）
• 运行时环境：OpenJDK 17 / 21，Docker / Kubernetes Pod / 本地 IDEA
• 触发条件：
  1. spring.profiles.active 指定的 profile 文件不存在（如笔误或 .gitignore 漏传）。
  2. 使用 spring.config.import 引用了挂载路径，但在无该卷挂载的环境下未标明可选。

StackTrace（堆栈日志）

控制台直接抛出异常并快速失败终止 JVM，阻断容器拉起：

2026-09-02 10:14:22.841 ERROR 1 --- [main] o.s.boot.SpringApplication : Application run failed

org.springframework.boot.context.config.ConfigDataLocationNotFoundException: Config data location 'classpath:/application-dev.yml' does not exist
    at org.springframework.boot.context.config.ConfigDataLocationNotFoundException.create(ConfigDataLocationNotFoundException.java:70)
    at org.springframework.boot.context.config.StandardConfigDataLocationResolver.getReferences(StandardConfigDataLocationResolver.java:152)
    at org.springframework.boot.context.config.StandardConfigDataLocationResolver.resolve(StandardConfigDataLocationResolver.java:128)
    at org.springframework.boot.context.config.ConfigDataLocationResolvers.resolve(ConfigDataLocationResolvers.java:114)
    at org.springframework.boot.context.config.ConfigDataEnvironment.processInitial(ConfigDataEnvironment.java:240)
    at org.springframework.boot.context.config.ConfigDataEnvironment.processAndApply(ConfigDataEnvironment.java:198)
    at org.springframework.boot.context.config.ConfigDataEnvironmentPostProcessor.postProcessEnvironment(ConfigDataEnvironmentPostProcessor.java:96)
    at org.springframework.boot.env.EnvironmentPostProcessorApplicationListener.onApplicationEnvironmentPreparedEvent(EnvironmentPostProcessorApplicationListener.java:109)
    at org.springframework.boot.env.EnvironmentPostProcessorApplicationListener.onApplicationEvent(EnvironmentPostProcessorApplicationListener.java:94)
    at org.springframework.context.event.SimpleApplicationEventMulticaster.doInvokeListener(SimpleApplicationEventMulticaster.java:178)
    at org.springframework.context.event.SimpleApplicationEventMulticaster.invokeListener(SimpleApplicationEventMulticaster.java:171)
    at org.springframework.context.event.SimpleApplicationEventMulticaster.multicastEvent(SimpleApplicationEventMulticaster.java:145)
    at org.springframework.boot.context.event.EventPublishingRunListener.environmentPrepared(EventPublishingRunListener.java:85)
    at org.springframework.boot.SpringApplicationRunListeners.environmentPrepared(SpringApplicationRunListeners.java:66)
    at org.springframework.boot.SpringApplication.prepareEnvironment(SpringApplication.java:344)
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:302)
    at com.example.demo.DemoApplication.main(DemoApplication.java:12)

Reproduce（复现代码）

在 src/main/resources/ 下仅放置默认的 application.yml：

spring:
  application:
    name: order-service
  profiles:
    active: dev
  config:
    import:
      - "file:/etc/secrets/config.properties"

但项目中并没有 application-dev.yml（可能因拼写为 application-devel.yml，或构建工具排除），同时宿主机目录 /etc/secrets/config.properties 不存在。

运行命令触发构建与启动：

mvn spring-boot:run

框架在引导阶段触发 ConfigDataLocationNotFoundException 并直接退出进程。

Root Cause（根因分析）

在 Spring Boot 2.4 之前，框架对缺失的 profile 配置文件默认采取静默容忍策略，如果未找到 application-dev.yml，通常只是忽略该文件并继续使用主配置。

自 Spring Boot 2.4 引入全新的 ConfigData API 起，底层由 StandardConfigDataLocationResolver 与 ConfigDataEnvironment 严格把关：

1. 显式指定被判定为强制依赖：当系统解析到显式配置的激活环境（如 -Dspring.profiles.active=dev）或显式引用的导入路径（spring.config.import）时，框架判定开发者是有意加载该资源的。
2. 缺乏可选标记（Optional Prefix）：如果目标文件为非必选项（例如容器内可能存在也可能不存在的挂载卷），但配置中未加上 optional: 前缀，Spring Boot 会认为关键配置遗失。为了防止系统带着半残的配置启动导致隐蔽的运行时灾难，设计上选择快速失败（Fail-Fast）。
3. 打包资源过滤：在多模块 Maven / Gradle 工程中，resources 配置若未包含指定 profile 的文件名模式，导致 jar 包内实际缺失对应资源。

The Fix（解决方案）

方案 1：检查 Profile 拼写与构建资源打包

确认 src/main/resources 下的文件命名完全符合 application-{profile}.yml 或 application-{profile}.properties 规范。如果使用 Maven 构建，确认 pom.xml 中未误排 YAML 文件：

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
            <includes>
                <include>application*.yml</include>
                <include>application*.properties</include>
            </includes>
        </resource>
    </resources>
</build>

方案 2：为外部导入路径添加 optional 前缀

如果外部配置（如 K8s Secret、ConfigMap 卷或外部挂载文件）只在特定宿主机存在，必须使用 optional: 前缀进行声明：

spring:
  config:
    import:
      - "optional:file:/etc/secrets/config.properties"
      - "optional:classpath:custom-config.yml"

增加 optional: 之后，StandardConfigDataLocationResolver 若探测到文件缺失，将跳过加载而不会抛出 ConfigDataLocationNotFoundException。

方案 3：使用 debug 模式排查实际生效路径

在启动参数中加入 --debug 选项：

java -jar target/demo-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev --debug

控制台会输出完整的 ConditionsEvaluationReport 以及配置加载位置列表，明确标出当前扫描的 classpath 根目录以及各配置源的来源文件路径。

References（参考来源）

• Spring Boot Reference: Config Data Migrationgithub
• Spring Boot ConfigDataLocationNotFoundException issue discussiongithub
• Spring Boot 外部化配置加载机制演进blog