SpringBoot 配置文件详细指南
一、前言
在 SpringBoot 开发中，配置文件是项目核心基础设施，所有端口、数据库、中间件、自定义业务参数都依赖配置文件实现解耦。
SpringBoot 提供两套主流配置文件：application.properties、application.yml (yaml)。很多初学者只会简单写配置，不懂加载优先级、多环境机制、配置覆盖规则、读取方式区别，导致频繁出现：
- 端口配置不生效
- 多环境切换冲突
- 配置占位符报错
- 数据库自动配置启动报错
- List/Map/ 嵌套对象无法绑定
本文从零系统化讲解 SpringBoot 全部配置体系，涵盖语法、区别、多环境、加载优先级、读取注解、变量引用、外部配置、实战报错解决，可直接作为学习与面试手册。
二、两种配置文件语法详解与对比
1. properties 传统键值配置（默认兼容）
核心语法规则
- 格式：key=value
- 层级嵌套：通过。无限拼接
- 注释：# 单行注释
- 所有值默认字符串类型，不会自动类型推断
- 数组通过下标 [0]、[1] 赋值
完整示例
properties
# 服务基础配置 server.port=8086 # 普通字段 person.lastname=zhangsan person.age=18 person.boss=false person.birth=2017-12-12 # Map集合 person.maps.k1=V1 person.maps.k2=12 # List数组 person.lists[0]=lisi person.lists[1]=zhaoliu # 嵌套对象 person.dog.name=daoge person.dog.age=122. yml 分层配置
核心语法规则
- 层级依靠 2 个空格缩进，绝对不能用 Tab
- 冒号：后面必须带一个空格
- 自动识别数据类型：数字、布尔、日期、集合
- 数组使用 - 符号定义
- 支持 --- 多文档分段，实现单文件多环境
完整示例
yaml
server: port: 8086 person: lastname: zhangsan age: 18 boss: false birth: 2017-12-12 maps: k1: V1 k2: 12 lists: - lisi - zhaoliu dog: name: daoge age: 123. properties VS yml 核心区别
表格
| 对比维度 | properties | yml |
|---|---|---|
| 层级表达 | 点拼接，嵌套多了极其冗长 | 缩进分层，结构清晰 |
| 数据类型 | 全部视为字符串 | 自动识别数字、布尔、日期、集合 |
| 数组写法 | 下标索引，繁琐 | 横杠遍历，简洁直观 |
| 多环境支持 | 不支持单文件分段 | 支持 --- 切分多环境 |
| 同级优先级 | 更高（同目录下 properties 覆盖 yml） | 低于 properties |
| 可读性 | 复杂配置极差 | 复杂配置首选 |
企业规范：统一使用 yml 作为主配置文件
三、SpringBoot 完整配置加载优先级
SpringBoot 配置遵循：高优先级覆盖低优先级，全部加载、同名覆盖。下面是从最高优先级 → 最低优先级完整排序。
1. 顶级优先级
- 命令行参数（最高）：java -jar demo.jar --server.port=9090，直接在虚拟机参数这里设计
- Java 系统属性：-Dserver.port=9090
- 操作系统环境变量：系统 / 容器环境变量
2. 外部配置文件
Jar 包同级目录，优先级高于项目内部配置，适合线上运维改配置无需重打包。
- file:./config/ Jar 同级 config 文件夹配置
- file:./ Jar 同级目录配置文件
3. 项目内部配置文件
- classpath:/config/resources/config 目录
- classpath:/resources 根目录（日常主配置）
4. 环境配置覆盖规则
激活某个 profile 时：application-{profile}.yml 覆盖 application.yml 同名配置，公共配置放主文件，环境差异放环境文件。
5. 自定义配置文件（最低）
通过 @PropertySource 加载的自定义 properties，优先级最低，会被所有 application 系列配置覆盖。
优先级总结口诀
命令行 > 系统变量 > 外部配置 > 内部环境配置 > 内部主配置 > 自定义配置文件
四、多环境配置示例（dev/test/prod）
开发、测试、生产环境端口、数据库、日志配置不同，SpringBoot 提供三种标准多环境方案。
方案一：单 yml 多分段（适合小型项目）
通过 --- 分割配置段，通过 spring.config.activate.on-profile 绑定环境。
yaml
# 默认全局配置（所有环境共享） server: port: 8086 # 开发环境 --- server: port: 8077 spring: config: activate: on-profile: dev # 生产环境 --- server: port: 8085 spring: config: activate: on-profile: prod方案二：多文件拆分
resources 下创建多环境文件，命名规范：application-{profile}.yml
- application.yml：公共配置（所有环境生效）
- application-dev.yml：开发环境
- application-prod.yml：生产环境
加载逻辑：激活 dev 时，公共配置 + dev 配置合并，dev 覆盖公共。
方案三：自定义外部配置文件
自定义 Person.properties 等文件，需要手动注解加载，Spring 不会自动识别。
java
@Component @PropertySource(value = "classpath:Person.properties", encoding = "UTF-8") @ConfigurationProperties(prefix = "person") public class Person { // 自动绑定自定义配置文件参数 }环境激活三种方式
- IDEA 启动配置：Active profiles 填写 dev /prod，可以直接运行相应的配置
- 代码启动：SpringApplication.run (Application.class, "--spring.profiles.active=dev")
- 命令行启动：java -jar demo.jar --spring.profiles.active=prod
五、配置文件两种读取方式对比
1. @Value 单字段读取
适合少量、零散、独立配置，语法简单。
java
@Component public class Person { // 读取配置，支持默认值（找不到配置用默认） @Value("${person.lastname:defaultName}") private String lastname; @Value("${person.age:18}") private Integer age; }缺点
- 不支持 List、Map、嵌套对象
- 字段多了代码冗余
- 无自动类型批量绑定
2. @ConfigurationProperties 批量对象绑定（推荐）
专门用于批量绑定、嵌套对象、集合类型，适配所有复杂配置场景。
完整实战代码
java
@Data @Component @ConfigurationProperties(prefix = "person") public class Person { private String lastname; private Integer age; private Boolean boss; private List<String> lists; private Map<String, String> maps; private Dog dog; } @Data public class Dog { private String name; private Integer age; }启动类开启配置绑定：
java
@SpringBootApplication @EnableConfigurationProperties(Person.class) public class SpringBootDemoApplication { }两种注解选型规范
- 少量零散配置：用 @Value
- 批量、对象、集合、嵌套配置：必须用 @ConfigurationProperties
六、配置变量引用与高级用法
1. 内部配置互相引用
yaml
project: name: springboot-demo info: desc: 项目名称：${project.name} # 配置不存在给默认值 server: port: ${server.port:8080}2. Maven 变量注入
pom 中定义版本，yml 直接读取，统一版本管理。 pom.xml：
xml
<properties> <mysql.version>9.7.0</mysql.version> </properties>yml 读取：
yaml
mysql: version: @mysql.version@七、打包后外部配置最佳实践
线上项目不推荐把配置全部打进 Jar，修改配置需要重打包。推荐外部配置文件方式：
- Jar 包同级新建 application-prod.yml
- 启动时指定环境：java -jar demo.jar --spring.profiles.active=prod
- 外部配置自动覆盖 Jar 内部配置，运维可直接改文件重启，无需改代码
八、总结
- 统一使用 yml，放弃 properties，结构更优雅，适配多环境
- 多环境文件拆分：application.yml + dev/prod 拆分，不使用单文件分段
- 复杂配置用对象绑定：全部使用 @ConfigurationProperties，放弃大量 @Value
- 测试环境排除数据源：单纯测试配置、端口时，exclude 数据源避免报错
- 线上使用外部配置：配置与代码解耦，方便运维迭代
- 公共配置抽主文件，差异化配置放环境文件，减少冗余
九、结尾
SpringBoot 配置看着简单，但优先级、加载机制、绑定规则、多环境原理是进阶核心。掌握本文全部内容，可以彻底解决 99% 的配置类报错，同时适配企业开发规范，也是面试高频考点。