Spring Boot 配置文件优先级详解

Spring Boot 配置文件优先级详解

你希望全面了解Spring Boot配置文件的优先级规则，我会从配置格式、内部文件路径、外部配置来源、特殊规则四个维度展开，结合实操示例帮你彻底掌握。

一、前置基础：配置文件格式优先级

Spring Boot核心支持两种配置文件格式，同一目录下的优先级关系为：

.properties（键值对格式） > .yml（层级格式）

说明：

1. .properties 格式：语法为 key=value，无缩进要求，兼容性更强（示例：server.port=8080）
2. .yml 格式：语法为 key: value（冒号后必须加空格），层级依赖缩进（2个空格，禁止tab），可读性更强（示例：server: port: 8080）
3. 若同一目录下同时存在 application.properties 和 application.yml，两者相同配置项以 .properties 为准，不同配置项会自动合并。

二、核心优先级1：项目内部配置文件路径（从高到低）

Spring Boot会自动扫描4个默认内部路径的配置文件（文件名固定为 application 或 application-{profile}，如 application-dev.properties），路径优先级从高到低排序如下：

优先级	路径	说明
1	./config/	项目根目录下的config子目录（打包后对应jar包同级的config文件夹）
2	./	项目根目录（打包后对应jar包同级目录）
3	classpath:/config/	类路径下的config子目录（项目中对应 resources/config/ 目录）
4	classpath:/	类路径根目录（项目中对应 resources/ 目录，默认配置存放位置，优先级最低）

实操示例：

若同时存在以下4个配置文件，均配置了 server.port：

1. ./config/application.properties → server.port=8080
2. ./application.properties → server.port=8081
3. classpath:/config/application.properties → server.port=8082
4. classpath:/application.properties → server.port=8083

最终项目启动端口为 8080（遵循路径优先级从高到低）。

三、核心优先级2：外部配置来源（高于所有内部配置）

除了项目内部配置文件，Spring Boot还支持多种外部配置来源，其优先级整体高于内部配置文件，从高到低排序如下：

1. 命令行参数（优先级最高）

启动jar包时通过 --key=value 传递的参数，会覆盖所有其他配置来源。

示例：

# 无论内部配置端口是多少，最终端口为8090
java -jar spring-boot-demo.jar --server.port=8090

2. JVM系统属性

启动时通过 -Dkey=value 传递的JVM参数，优先级仅次于命令行参数。

示例：

# 端口配置为8091，若与命令行参数冲突，以命令行为准
java -Dserver.port=8091 -jar spring-boot-demo.jar

3. 操作系统环境变量

操作系统级别的环境变量（Windows"环境变量"/Linux export 命令配置），优先级高于配置中心和外部指定配置文件。

说明：

• Spring Boot会自动转换命名规则：驼峰转下划线、小写转大写，示例：
  配置项 spring.profiles.active 对应环境变量 SPRING_PROFILES_ACTIVE

• Linux示例：

  # 配置激活prod环境
  export SPRING_PROFILES_ACTIVE=prod
  java -jar spring-boot-demo.jar

4. 分布式配置中心（Nacos/Consul/Spring Cloud Config）

分布式场景下的统一配置管理，优先级高于本地外部配置文件，适合多实例统一配置。

说明：配置中心的配置可动态刷新，优先级可通过配置调整（默认高于本地所有配置）。

5. 外部指定路径配置文件

通过 spring.config.location 或 spring.config.additional-location 指定外部配置文件路径，优先级高于项目内部配置文件。

两者区别：

• spring.config.location：覆盖默认配置路径（内部4个路径失效，仅加载指定路径配置）
• spring.config.additional-location：追加 配置路径（保留默认4个路径，指定路径优先级更高，推荐使用）
  示例：

# 追加/opt/config/目录下的配置文件，优先级高于内部配置
java -jar spring-boot-demo.jar --spring.config.additional-location=/opt/config/

四、特殊优先级规则

1. Profile配置文件的覆盖规则

Spring Boot支持环境隔离配置（application-{profile}.properties/yml），其优先级规则：

• 激活的Profile配置 > 默认配置（application.properties/yml）
• 多个Profile激活时（通过 spring.profiles.active=dev,test 指定），后面的Profile会覆盖前面的相同配置项，不同配置项合并
• Profile配置同样遵循「路径优先级」和「格式优先级」

示例：

1. classpath:/application.properties → server.port=8080、spring.application.name=demo
2. classpath:/application-dev.properties → server.port=8081、spring.datasource.url=xxx
3. classpath:/application-test.properties → server.port=8082
4. 激活命令：--spring.profiles.active=dev,test

最终配置：

• server.port=8082（test覆盖dev，dev覆盖默认）
• spring.application.name=demo（默认配置，无覆盖）
• spring.datasource.url=xxx（dev配置，无覆盖）

2. 配置项的核心原则："覆盖+合并"

• 覆盖：相同配置项，高优先级来源覆盖低优先级来源（如命令行覆盖内部配置）
• 合并：不同配置项，所有来源的配置项会统一加载，不会丢失（如内部配置了server.port，外部配置了spring.application.name，两者同时生效）

3. 自定义配置文件（@PropertySource）

通过 @PropertySource 注解加载自定义配置文件（如 custom.properties），其默认优先级低于所有Spring Boot默认配置来源 ，可通过 order 属性调整优先级（值越小，优先级越高）。

示例：

// 加载自定义配置文件，指定优先级（默认最低）
@SpringBootApplication
@PropertySource(value = "classpath:custom.properties", order = 10)
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

五、优先级总览（从高到低，核心总结）

1. 命令行参数（--key=value）
2. JVM系统属性（-Dkey=value）
3. 操作系统环境变量
4. 分布式配置中心（Nacos/Consul等）
5. 外部指定路径配置（spring.config.additional-location > spring.config.location）
6. 项目根目录 ./config/ 下的配置文件（.properties > .yml）
7. 项目根目录 ./ 下的配置文件（.properties > .yml）
8. 类路径 classpath:/config/ 下的配置文件（.properties > .yml）
9. 类路径 classpath:/ 下的配置文件（.properties > .yml，默认存放位置）
10. @PropertySource 加载的自定义配置文件（默认最低）

六、常见误区提醒

1. 误区1：认为 .yml 优先级高于 .properties → 实际同一目录下 .properties 优先级更高
2. 误区2：多个Profile激活时忽略顺序 → 后面的Profile会覆盖前面的相同配置
3. 误区3：滥用 spring.config.location → 会覆盖默认配置路径，推荐使用 spring.config.additional-location 追加配置
4. 误区4：忽略命令行参数的最高优先级 → 线上调试时可通过命令行快速覆盖配置，无需修改配置文件

总结

1. 核心优先级逻辑：外部配置 > 内部配置 、properties > yml 、特定路径 > 默认路径 、Profile配置 > 默认配置
2. 最高优先级是命令行参数，最低优先级默认是 @PropertySource 自定义配置
3. 配置冲突时遵循"覆盖原则"，配置不冲突时遵循"合并原则"
4. 线上部署时，优先通过 spring.config.additional-location 指定外部配置文件，方便修改无需重新打包