SpringBoot 配置文件详细指南

一、前言

在 SpringBoot 开发中，配置文件是项目核心基础设施，所有端口、数据库、中间件、自定义业务参数都依赖配置文件实现解耦。

SpringBoot 提供两套主流配置文件：application.properties、application.yml (yaml)。很多初学者只会简单写配置，不懂加载优先级、多环境机制、配置覆盖规则、读取方式区别，导致频繁出现：

1. 端口配置不生效
2. 多环境切换冲突
3. 配置占位符报错
4. 数据库自动配置启动报错
5. 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=12

2. 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: 12

3. properties VS yml 核心区别

表格

对比维度	properties	yml
层级表达	点拼接，嵌套多了极其冗长	缩进分层，结构清晰
数据类型	全部视为字符串	自动识别数字、布尔、日期、集合
数组写法	下标索引，繁琐	横杠遍历，简洁直观
多环境支持	不支持单文件分段	支持 --- 切分多环境
同级优先级	更高（同目录下 properties 覆盖 yml）	低于 properties
可读性	复杂配置极差	复杂配置首选

企业规范：统一使用 yml 作为主配置文件

三、SpringBoot 完整配置加载优先级

SpringBoot 配置遵循：高优先级覆盖低优先级，全部加载、同名覆盖。下面是从最高优先级 → 最低优先级完整排序。

1. 顶级优先级

1. 命令行参数（最高）：java -jar demo.jar --server.port=9090，直接在虚拟机参数这里设计
2. Java 系统属性：-Dserver.port=9090
3. 操作系统环境变量：系统 / 容器环境变量

2. 外部配置文件

Jar 包同级目录，优先级高于项目内部配置，适合线上运维改配置无需重打包。

1. file:./config/ Jar 同级 config 文件夹配置
2. file:./ Jar 同级目录配置文件

3. 项目内部配置文件

1. classpath:/config/resources/config 目录
2. 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 {
    // 自动绑定自定义配置文件参数
}

环境激活三种方式

1. IDEA 启动配置：Active profiles 填写 dev /prod，可以直接运行相应的配置
2. 代码启动：SpringApplication.run (Application.class, "--spring.profiles.active=dev")
3. 命令行启动：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;
}

缺点

1. 不支持 List、Map、嵌套对象
2. 字段多了代码冗余
3. 无自动类型批量绑定

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 {
}

两种注解选型规范

1. 少量零散配置：用 @Value
2. 批量、对象、集合、嵌套配置：必须用 @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，修改配置需要重打包。推荐外部配置文件方式：

1. Jar 包同级新建 application-prod.yml
2. 启动时指定环境：java -jar demo.jar --spring.profiles.active=prod
3. 外部配置自动覆盖 Jar 内部配置，运维可直接改文件重启，无需改代码

八、总结

1. 统一使用 yml，放弃 properties，结构更优雅，适配多环境
2. 多环境文件拆分：application.yml + dev/prod 拆分，不使用单文件分段
3. 复杂配置用对象绑定：全部使用 @ConfigurationProperties，放弃大量 @Value
4. 测试环境排除数据源：单纯测试配置、端口时，exclude 数据源避免报错
5. 线上使用外部配置：配置与代码解耦，方便运维迭代
6. 公共配置抽主文件，差异化配置放环境文件，减少冗余

九、结尾

SpringBoot 配置看着简单，但优先级、加载机制、绑定规则、多环境原理是进阶核心。掌握本文全部内容，可以彻底解决 99% 的配置类报错，同时适配企业开发规范，也是面试高频考点。