1. 为什么同一个项目中会有两个配置文件：从一次启动失败说起
先说个我自己的经历。去年给客户做一套基于Nacos的服务治理改造，项目从GitLab上拉下来之后，我直接mvn spring-boot:run，结果启动直接报错，提示找不到bootstrap.yml里的配置项。当时第一反应是"代码写错了？"，后来翻了一圈才发现，问题出在我对这两个文件的理解还停留在"二选一"的层面。
很多刚接触Spring Boot的同学都会有这个疑问：为什么项目里同时存在bootstrap.yml和application.yml？它们不都是配置文件吗？放在一起不会冲突吗？说实话，我刚入行的时候也这么想过，甚至一度以为bootstrap.yml是某种历史遗留产物，删掉也无所谓。直到我真正接触Spring Cloud、接手微服务项目之后，才搞明白这两个文件承担着完全不同的职责。
简单说，application.yml负责应用本身的常规配置，bootstrap.yml负责应用启动引导阶段的配置。这个"引导阶段"听起来很抽象，但你只要记住一句话：如果你的应用需要在真正启动之前，先去连接配置中心拉取配置、处理加密属性、加载远程配置，那么这些"前置动作"所需要的配置，就必须放在bootstrap.yml里。
这篇文章我会把这两个文件从设计目的、加载时机、优先级规则到实战写法完整拆开讲一遍，并结合spring cloud 2020版本之后的行为变化，聊一聊什么时候必须保留bootstrap.yml、什么时候可以彻底移除它。无论你是刚写第一个Spring Boot程序的初学者，还是已经在做微服务改造的开发者，这篇文章都应该能帮你省下不少排查时间。
2. 加载流程与启动时序：bootstrap.yml 凭什么先于 application.yml 生效
要理解这两个文件的区别，先得搞清楚Spring Boot启动时到底按什么顺序读配置。这部分的重点不在于"记住顺序"，而在于理解Spring Boot为什么要这样设计。
2.1 Spring Boot的配置加载顺序拆解
当你在IDE里点击Run，或者执行java -jar app.jar的时候，Spring Boot的启动流程大致是这样的：
- 创建SpringApplication实例
- 通过
SpringApplication.run()触发启动 - 监听器、初始化器逐一生效
- 准备Environment（环境对象）
- 创建ApplicationContext（应用上下文）
- 刷新上下文，完成Bean的创建和注入
在这条链路上，配置文件是在"准备Environment"这个阶段被加载的。Spring Boot默认会依次寻找bootstrap.yml和application.yml（以及对应的.properties文件），然后把解析出的属性放入Environment中。
这里有一个关键的细节：bootstrap.yml的加载由BootstrapApplicationListener触发，它的执行优先级极高，会在application.yml加载之前先读取内容，并且把解析结果写入一个名为BootstrapContext的独立上下文环境中。这个BootstrapContext最终会成为主ApplicationContext的父容器。
你可以把整个过程理解成盖房子的两个阶段：
bootstrap.yml负责的是"打地基"——先确定到哪里找建材、用什么标号的水泥、施工队什么时候进场；application.yml负责的是"内部装修"——墙刷什么颜色、地板用什么材质、家具怎么摆。
地基没打好之前，装修方案再漂亮也执行不了。
2.2 为什么bootstrap.yml里的内容不能被application.yml覆盖
这是很多人掉过坑的地方。假设你在bootstrap.yml里配置了：
spring: application: name: order-service然后在application.yml里也写了：
spring: application: name: payment-service启动之后你可能会发现，应用名称仍然是order-service。为什么？因为bootstrap.yml先加载，而且它属于父上下文，父上下文的属性优先于子上下文。尽管application.yml里写了新的值，但子上下文无法覆盖父上下文中已有的属性，最终生效的还是先加载的那个。
在实际项目中，最常见的后果就是：你在application.yml里改了spring.application.name，但服务注册到Nacos或Eureka上时，显示的仍然是bootstrap.yml里那个旧名字。排查半天，最后发现改错文件了。
2.3 Spring Cloud 2020+带来的行为变化
这里必须单独提一下版本差异，因为这是近两年咨询量最高的问题之一。
从Spring Cloud 2020.0（代号Ilford）开始，官方默认关闭了bootstrap上下文。也就是说，如果你用的是spring cloud 2020.0或更高版本，并且没有额外做配置，那么bootstrap.yml默认是不会被加载的。这个改动让很多老项目升级之后直接翻车——原来放在bootstrap.yml里的Nacos地址、加密配置全部失效。
如果项目确实需要bootstrap机制，官方给出的方案是手动引入依赖：
<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-bootstrap</artifactId> </dependency>引入之后，需要在application.yml或bootstrap.yml里显式开启：
spring: cloud: bootstrap: enabled: true这一变化让"什么时候用bootstrap.yml"这个问题变得更加需要认真思考。如果你还在用旧版本的Spring Cloud，保留原有写法没问题；如果你已经升级到了2020+，那么必须明确知道自己是否需要bootstrap机制，不能盲目照抄老项目的配置文件。
3. 各自的核心职责：引导配置与应用配置到底分家分在哪
现在把两个文件切开来看。bootstrap.yml和application.yml看上去都是YAML文件，但它们的使命完全不同。这一节我把它们各自负责的内容逐个列清楚。
3.1 bootstrap.yml负责的引导阶段事务
bootstrap.yml是Spring Cloud体系下的产物，它的核心任务是处理应用启动时那些"前置条件"。具体来说，常见的配置内容包括：
- 配置中心地址：比如Nacos的
server-addr、Spring Cloud Config的uri。应用必须先知道配置中心在哪，才能在启动过程中拉取远程配置； - 服务注册中心地址：应用启动后要注册到哪个注册中心，这个信息也属于引导阶段就要确定的内容；
- 应用名称：
spring.application.name通常放在这里，因为无论是注册中心还是配置中心，都需要通过应用名来区分不同服务； - 加密/解密的密钥信息：比如数据库密码在配置中心里是密文，本地需要持有解密的密钥或Salt值；
- 一些需要在上下文刷新前就必须生效的日志或系统参数。
举个例子，一个典型的bootstrap.yml长这样：
spring: application: name: order-service cloud: nacos: config: server-addr: 127.0.0.1:8848 file-extension: yaml namespace: dev-01 discovery: server-addr: 127.0.0.1:8848应用启动时，Spring Cloud会先用这份配置去连接Nacos，从配置中心拉取order-service.yaml或其他远程配置文件，这些远程配置会在application.yml加载之前合并进Environment。
3.2 application.yml负责的应用运行期常规配置
application.yml则是Spring Boot本身的标准配置文件，它描述的是"应用正常运行需要哪些配置"，包括但不限于：
- 服务端口：
server.port - 数据源：
spring.datasource.url、spring.datasource.username - Redis、MQ等中间件的连接信息
- 业务自定义参数
- 日志级别
- JPA/MyBatis等框架的配置
一个比较标准的application.yml片段：
server: port: 8081 spring: datasource: url: jdbc:mysql://localhost:3306/order_db?useSSL=false username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver redis: host: localhost port: 6379 logging: level: com.example.order: debug这里的配置逻辑很直白：应用本身怎么跑、连接什么资源、业务参数怎么定，都归application.yml管。它不需要在启动早期生效，等Spring容器真正初始化时读取就来得及。
3.3 隐藏在场景背后的选择逻辑
判断一段配置该放哪个文件，你只需要回答一个问题：这段配置在"应用启动早期"就被需要吗？
如果答案是"是"，放bootstrap.yml；如果答案是"否，等Bean初始化时再说"，放application.yml。
举两个极端例子：
- 数据库连接池的初始化发生在DataSource Bean创建阶段，此时主ApplicationContext已经开始刷新，所以数据源配置放
application.yml没问题； - 但从Nacos拉取远程配置的动作，发生在Environment准备阶段，这个阶段连DataSource都还没影儿，所以必须先通过
bootstrap.yml拿到Nacos地址，才能执行拉取。
很多初学者会把Nacos地址也写进application.yml，然后本地跑的时候一切正常，一部署到测试环境就出问题。原因就是：测试环境的application.yml是外部挂载的，或者通过环境变量注入的，而引导阶段的配置没有被正确覆盖。这种问题排查起来极其痛苦，因为你甚至不知道配置是从哪里读进来的。
4. 配置优先级与覆盖规则：同一个key被多处定义时听谁的
配置的优先级问题，本质上是Spring Boot的PropertySource机制在起作用。简单理解：属性源有先后顺序，排在越前面的，优先级越高。
4.1 从命令行到bootstrap.yml的完整覆盖顺序
Spring Boot的配置优先级大致如下（从高到低）：
- 命令行参数
- Java系统属性（
System.getProperties()） - 操作系统环境变量
application-{profile}.yml（指定Profile的配置文件）application.ymlbootstrap-{profile}.ymlbootstrap.yml- 通过
@PropertySource加载的配置
这里要注意一个容易混淆的点：bootstrap.yml加载很早，但在优先级列表里它其实是垫底的。也就是说，bootstrap.yml里的默认值很容易被同名的application.yml配置覆盖，除非该配置在父上下文中已经生效并且子上下文不重复定义。
用大白话讲：加载顺序早不等于优先级高。bootstrap.yml是先被读进来了，但它更像是"底层默认值"，如果后面有更高优先级的配置源定义了同一个key，最终生效的是后面那个。这就是为什么很多人在application.yml里配置了server.port=8080，却能被外部application-prod.yml里的9090覆盖掉。
4.2 Profile（环境）对两个文件的影响
跟环境相关的配置规则也值得单独说。假设你有三个环境：dev、test、prod。
通常的做法是：
application.yml里放公共配置；application-dev.yml、application-test.yml、application-prod.yml分别放各自的差异化配置。
bootstrap.yml也支持这种命名规则：
bootstrap.yml放公共的引导配置；bootstrap-dev.yml、bootstrap-prod.yml放不同环境的引导差异。
如果你在bootstrap.yml里加了spring.profiles.active=dev，那么Spring Cloud会额外去加载bootstrap-dev.yml。但这里有个鸡生蛋的问题：spring.profiles.active本身就得在引导阶段确定，可它放在bootstrap.yml里时，加载时机是否来得及生效，取决于具体实现版本。稳妥的做法是，通过启动命令行参数或环境变量指定Profile：
java -jar app.jar --spring.profiles.active=dev或者
SPRING_PROFILES_ACTIVE=dev java -jar app.jar在实际项目中，我见过有人把spring.profiles.active写死在bootstrap.yml里，导致测试环境想切配置却怎么都切不过去。我的建议是：环境相关的开关尽量通过外部手段控制，不要在配置文件里写死，否则在不同环境的部署脚本里很难统一管理。
4.3 配置覆盖的调试方法：如何快速找到属性来源
做配置问题排查的时候，最有用的一个工具是Spring Boot Actuator的/env端点。启动时加上--debug参数，或者配置：
management: endpoints: web: exposure: include: env,configprops启动后访问/actuator/env，你可以看到每个配置项的来源和优先级顺序，比如某个spring.application.name是从哪个PropertySource里加载的，这个PropertySource排在第几位。这个信息对排查"为什么配置不生效"简直救命。
另外，用--debug启动Spring Boot时，日志里会打印所有被加载的配置文件和属性源列表。我第一次用这个命令排查问题时，直接从日志里发现了一个我完全没想到的来源——~/.spring-boot-dev-tools.properties，那是DevTools自动加载的配置文件，优先级还挺高。这种隐藏属性源不跑一下日志根本发现不了。
5. 从零到一：一个真实项目的双文件配置实操
光讲理论没意思，我直接用一个实际项目的配置过程演示一遍。假设我们要做一个订单服务，使用Nacos作为配置中心和注册中心，本地开发环境，Spring Boot版本2.6.x，Spring Cloud版本2021.0.x。我们要在这个版本组合下把bootstrap机制重新打开，然后跑通配置拉取。
5.1 依赖与项目结构准备
先在pom.xml里引入必要的依赖：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.6.3</version> <relativePath/> </parent> <properties> <spring-cloud.version>2021.0.1</spring-cloud.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-bootstrap</artifactId> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId> <version>2021.1</version> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId> <version>2021.1</version> </dependency> </dependencies> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>${spring-cloud.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>这里有几个细节值得说明：
spring-cloud-starter-bootstrap是重新开启bootstrap机制的关键；- Nacos的starter需要单独指定版本，它和Spring Cloud主版本不是同一个版本号体系；
- 如果少了
spring-cloud-starter-bootstrap，即使配置文件里写着bootstrap.yml，2021.0.x版本也不会主动加载它。
5.2 bootstrap.yml与application.yml的最终配置
项目resources目录下建立两个文件。
bootstrap.yml：
spring: application: name: order-service cloud: nacos: config: server-addr: 127.0.0.1:8848 file-extension: yaml group: DEFAULT_GROUP discovery: server-addr: 127.0.0.1:8848application.yml：
server: port: 8081 spring: cloud: bootstrap: enabled: true datasource: url: jdbc:mysql://localhost:3306/order_db?useUnicode=true&characterEncoding=utf8 username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver management: endpoints: web: exposure: include: env,configprops注意spring.cloud.bootstrap.enabled=true，这个开关写在application.yml里也能生效（别问为什么不是必须在bootstrap.yml里写，因为到这一步时Spring Boot内部的bootstrap listener已经在运行了，它读取的是Environment里的值）。
5.3 Nacos配置中心的数据准备
在Nacos控制台上，新建一个dataId=order-service.yaml的配置，Group选DEFAULT_GROUP，配置格式选YAML，内容示例：
order: timeout: 5000 max-retry: 3 logging: level: com.example.order: debug然后启动应用。如果一切正常，控制台会有类似日志：
Located property source: [BootstrapPropertySource {name='bootstrapProperties-order-service.yaml'}]这条日志很关键，它说明远程配置已经被拉取并合并到环境中。你可以写一个接口验证一下：
@RestController public class ConfigController { @Value("${order.timeout}") private String timeout; @GetMapping("/timeout") public String getTimeout() { return timeout; } }当你在Nacos上修改order.timeout，再通过/actuator/refresh触发刷新（需要额外引入spring-boot-starter-actuator并开启refresh端点），就能看到配置动态变更的效果。
我实际操作时踩过一个坑：Nacos地址配置在bootstrap.yml里是127.0.0.1:8848，结果部署到服务器上忘了改，应用一直报"无法连接Nacos"。排查了半天发现不是网络问题，是bootstrap.yml里的地址没被外部的application-prod.yml覆盖。原因就是前面讲的：引导阶段配置优先从bootstrap.yml读取，外部application.yml里配置Nacos地址时，时机上来不及。这个场景如果你想做成外部化配置，就得用环境变量（比如SPRING_CLOUD_NACOS_CONFIG_SERVER_ADDR）或者在启动命令里用参数覆盖，而不是指望着通过application.yml去覆盖。
6. 到底要不要bootstrap.yml：团队项目里我建议的执行标准
最后这部分聊一点我在实际团队管理和项目评审中的体会。bootstrap.yml不是必选项，它是有明确的适用边界的。判断标准不复杂，但很多人容易走极端。
6.1 需要保留bootstrap.yml的典型场景
以下几种情况你大概率需要保留bootstrap.yml：
- 使用了Nacos Config或Spring Cloud Config作为配置中心：应用需要在启动早期拿到配置中心的地址并拉取远程配置；
- 使用了Vault等加密配置服务：解密动作必须在应用上下文创建之前完成；
- 配置了多项需要在Environment准备阶段就要确定的基础参数：比如应用名、激活的Profile等；
- 团队项目里存在大量外部化配置需求：因为
bootstrap.yml适合存放那些"所有环境都保持一致的引导配置"，而环境差异可以通过外部参数注入。
6.2 可以移除bootstrap.yml的典型场景
反过来，如果你的项目满足这些条件，可以考虑去掉bootstrap.yml：
- 单体应用：没有注册中心、没配置中心，只有本地的
application.yml； - 使用Spring Cloud 2020+并已迁移到
spring.config.import机制：官方推荐的新写法，可以直接在application.yml里导入远程配置； - 所有引导配置都可以通过环境变量或命令行参数注入。
新版写法示例：
spring: config: import: nacos:order-service.yaml加上：
spring: cloud: nacos: config: server-addr: 127.0.0.1:8848这样即使没有bootstrap.yml，配置中心的内容也能导入。
6.3 两份配置文件对比速查表
| 对比维度 | bootstrap.yml | application.yml |
|---|---|---|
| 定位 | 应用启动引导阶段配置 | 应用运行期常规配置 |
| 加载时机 | 先于application.yml，由BootstrapApplicationListener触发 | Spring Boot标准配置加载流程中执行 |
| 核心作用 | 连接配置中心、注册中心、解密密钥等前置信息 | 服务端口、数据源、业务参数、日志级别等 |
| 依赖环境 | 主要在Spring Cloud体系下需要 | Spring Boot本身就需要 |
| 上下文归属 | 属于BootstrapContext（主Context的父级） | 属于主ApplicationContext |
| 生命周期 | 应用启动早期即失效 | 贯穿应用整个运行期 |
| 典型场景 | Nacos Config、Spring Cloud Config、Vault集成 | 常规业务应用配置 |
| 默认启用状态 | Spring Cloud 2020+默认关闭 | 始终启用 |
6.4 我建议的执行标准
在团队协作层面，我的个人倾向是：尽量用更现代的方式替代bootstrap机制，但不要为了"新"而强行迁移。如果你维护的是一个还在正常运行的老项目，bootstrap.yml用得好好的，完全没有必要为了追新而移除它。但如果是新项目，我会建议优先采用spring.config.import方案，因为这样配置文件更少、心智负担更低，排查问题也更直观。
最后再分享一个小技巧：当你需要临时验证某段配置到底是在哪个阶段被加载的，可以在bootstrap.yml里临时加一行logging.level.org.springframework.cloud.bootstrap=debug，然后启动看日志。这个开关能把bootstrap过程的完整执行链路打出来，比看源码高效得多。我在排查几次诡异的配置失效问题时，都是靠这行日志定位到真正的原因。
