写配置文件的文章很多，但大多绕来绕去，真正能帮你把application.yml和application.properties一次吃透的很少。今天这篇，我就用自己的学习笔记，把 SpringBoot 核心配置这块掰开了讲清楚。
说明一下，这篇是给正在学 SpringBoot 的小伙伴看的，尤其是那些已经能跑起一个 Demo，但一碰到配置就犯迷糊的人。也适合写了几年代码，但遇到配置优先级、多环境切换问题时还要去翻文档的开发者。看完这篇文章，不敢说你变成配置专家，但日常开发里 90% 的配置场景，你都能心里有数。
1. 配置文件选型与整体设计思路
1.1 为什么 SpringBoot 还有配置文件
很多人刚接触 SpringBoot 时都有个错觉：这框架只靠注解就能搞定一切。确实，自动配置帮我们省掉了大量 XML 配置，但它并没有消灭配置这件事本身。数据库连哪个？端口号多少？日志打印到哪个级别？缓存用 Redis 还是本地内存？这些不可能靠猜测决定，必然有一个地方做统一设定。application.yml和application.properties就是 SpringBoot 约定的配置入口。
约定优于配置，但约定解决的是"大部分情况下的默认行为"。比如你没写端口，那就默认 8080；没配数据库，就按 H2 内存库处理。可一旦你上了生产，端口可能是 8443，数据库是 MySQL，密码不可能写在代码里，这些都得靠配置文件来覆盖默认值。说到底，配置文件的存在价值就是让你在不改代码的前提下，通过外部化配置去适配不同运行场景。
还有一个很多新手没意识到的事：SpringBoot 的配置输入源远不止这两个文件。命令行参数、环境变量、JVM 系统属性都能成为配置来源。配置文件只是其中最常用、最直观的一种。理解这一点，后面讲优先级时才不会懵。
1.2 yml 和 properties 到底选哪个
这是每个 SpringBoot 新手必遇到的第一个选择。application.properties是 Spring Boot 历史上最早的配置格式，扁平结构，用点号分隔每一级 key，例如server.port=8080。application.yml则是随着 Spring 生态发展被引入的，使用 YAML 格式，靠缩进表达层级关系。
两边其实都能完成同样的配置任务，语言层面的区别主要在这几点：
- 可读性：层级少的时候 properties 看着干净，层级一多（比如
spring.datasource.hikari.connection-timeout），properties 的 key 会变得很长；yml 用缩进表达从属关系，逻辑上更像一棵树。 - 类型表达：YAML 天然支持集合、Map、布尔值、数字类型，写起来直观；properties 全是字符串，虽然 SpringBoot 最终也会做类型转换，但写起来繁琐。
- 多环境支持：单个 yml 可以用
---分隔多个文档块，在一个文件里模拟多个 profile；properties 必须拆多个文件（后面细讲）。 - 容错性：properties 更宽容，错了也不太影响整体解析；yml 对空格缩进极其敏感，一个缩进错误整个文件直接解析失败，报错还特别难懂。
我的做法是：新项目优先用 yml，因为可读性好、层级清晰，团队协作时 diff 也更友好；如果项目里已经有大量 properties 文件，或者你的团队对 YAML 缩进实在不敏感（总有同事把空格对齐搞砸），老老实实用 properties 反而少操一份心。这没有"哪个更好"，只有"哪个更适合你们的团队"。
2. 核心配置项逐项拆解与实操
2.1 服务端口与上下文路径
先聊聊最基础但最容易出问题的部分。配置服务的端口和路径，在 properties 里是这样写：
server.port=8080 server.address=0.0.0.0 server.servlet.context-path=/api切换成 yml 是这样：
server: port: 8080 address: 0.0.0.0 servlet: context-path: /apiserver.port不用多说，启动端口。但有几个细节值得注意。server.address我单独列出来是因为很多人在部署到 Linux 服务器时踩过坑：默认绑定的是0.0.0.0，也就是所有网卡地址都能访问。如果你出于安全考虑想让服务只能本机访问，把它改成127.0.0.1；反向代理场景下，也建议显式配置，防止预期外暴露。server.servlet.context-path则是给所有接口加统一前缀，比如你原本接口是/user/list，配置后变成/api/user/list。
这里有个冷知识：SpringBoot 在随机端口场景有一个很方便的用法。
server.port=0端口设为 0 时，SpringBoot 会随机找一个可用端口启动。这在单测里很常见，但你得从ServletWebServerApplicationContext里拿到实际端口，否则测试根本打不进去。这个技巧在日常业务开发里用得少，不过面试问到@SpringBootTest的端口隔离原理时能派上用场。
2.2 数据库与连接池配置
数据库配置是配置文件的重头戏。拿最常见的 MySQL 举例：
spring: datasource: url: jdbc:mysql://localhost:3306/mall?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver你至少得理解 URL 里这三个参数的作用。useUnicode和characterEncoding是防止中文乱码的老组合；serverTimezone必须设置是因为 5.x 版本的 MySQL 驱动默认取的时区和你的服务器时间不一致，会在日期时间字段上出问题；useSSL现在的 MySQL 8.0 默认 SSL，如果你本地没有配置证书，就把它显式关掉，否则启动时会有一堆警告日志。
再说driver-class-name。我在无数答疑帖里看到有人纠结要不要写。SpringBoot 会根据 URL 自动推断驱动类，比如看到jdbc:mysql就知道用com.mysql.cj.jdbc.Driver。但如果你用的是某些小众数据库或者有多个驱动 jar 共存，还是显式写上最保险。另外注意 MySQL 8.0 用的是cj那个驱动，老版的com.mysql.jdbc.Driver已经在新版本中移除了。
连接池这块一定要单独提一下。SpringBoot 2.x 开始默认使用的连接池是 HikariCP，这是目前性能最好的连接池之一。没有额外引入其它连接池依赖时，你配了spring.datasource下这几个参数，Hikari 就会自动接管。如果你想调连接池参数：
spring: datasource: hikari: minimum-idle: 5 maximum-pool-size: 20 connection-timeout: 30000 idle-timeout: 600000maximum-pool-size是我见过调节最多的参数。起初大家都觉得越大越好，但数据库性能是有限的，过度增加的连接只会造成资源浪费。一般建议 QPS 视业务情况配在 10~50 之间，配之前先想清楚数据库能撑多少并发，而不是面向百度编程。
2.3 日志配置从入门到进阶
日志配置最大的痛点不是要不要打日志，而是打到哪、怎么控制级别。SpringBoot 默认只输出到控制台，日志级别是 INFO。很多人发现项目跑起来后日志狂刷屏，想过滤到只看到自己的包，于是就有了这段：
logging: level: root: warn com.example.mall: debug file: name: logs/application.log第一行把全局日志级别调到 WARN，整个世界安静了。第二行单独把你的业务包拎出来设为 DEBUG——这就是"全局收紧、局部放开"的策略。注意root是最顶层，它管着所有包，但子包可以覆盖它的级别。
logging.file.name是 SpringBoot 2.3 之后的写法，指定了文件名和路径。在 2.3 之前用的是logging.file（纯文件名）和logging.path（纯路径）两个分开的属性，新的name能同时指定目录和文件，更顺手。日志文件默认按大小轮转，默认上限 10MB。
进阶一点，当你引入 logback-spring.xml 时，配置文件的logging.*属性会自动失效，因为 logback-spring.xml 优先级更高。所以有不少人改写了 logback 后，觉得"为什么我的 logging.level 配置没生效"，查一圈才发现是两者打架。如果引入自定义 logback，你就应该把日志相关配置全面迁移到 XML 里统一管理，不要两个地方各写一半，维护成本会翻倍。
2.4 自定义配置项的多种读取方式
配置里少数情况是 SpringBoot 自带属性，多数情况业务总会加一些自己的配置。我见过有人把业务参数硬编码到代码里，然后一变需求就改代码重新发布，时间长了就变成"重构黑历史"。正确的姿势是把这类参数放配置：
mall: jwt: secret: aabbccddeeffgghh expire-days: 7读取方式我按推荐程度从低到高讲。
第一种，@Value直接注入：
@Value("${mall.jwt.secret}") private String jwtSecret;看着简单，但每个字段都要写一行，十几个参数时类里全是@Value，而且类型转换是弱约束，字符串转数字报错时只有程序启动那一下才暴露。@Value适合临时取一两个值，不适合大规模管理配置。
第二种，@ConfigurationProperties绑定一个配置类，这是正规军做法：
@Component @ConfigurationProperties(prefix = "mall.jwt") public class JwtProperties { private String secret; private Integer expireDays; // getter/setter 省略 }这里有个小坑：@ConfigurationProperties绑定的是 setter 方法（基于 JavaBean 规范），所以你必须提供 setter，否则绑定不上。如果你用的是 Lombok，@Data就能解决。SpringBoot 3.x 里也支持用@ConfigurationProperties注册到容器，不一定需要@Component，在启动类加@EnableConfigurationProperties(JwtProperties.class)也是可以的。这两种方式哪种更好？我个人的习惯是：JwtProperties 这种业务性很强的类用@Component让 Spring 自动扫到；如果是通用组件包的属性类，用@EnableConfigurationProperties显式注册更灵活。
3. 多环境配置与配置优先级
3.1 多环境配置拆分与切换
项目开发离不开环境区分：本地环境、测试环境、生产环境，数据库地址不一样、日志级别不一样、Redis 地址不一样。最粗暴的方案是每次上线前手动改配置文件，但这本质上是在给事故写剧本。SpringBoot 提供了 profile 机制来解决这个问题。
最常见的方式是多文件：application-dev.properties、application-test.properties、application-prod.properties，然后主文件里用spring.profiles.active指定激活哪个环境：
spring.profiles.active=dev在 yml 里还可以用单文件多文档块的方式，虽然是把环境拆在一个文件里：
spring: profiles: active: dev --- spring: config: activate: on-profile: dev server: port: 8081 --- spring: config: activate: on-profile: prod server: port: 8082注意写法，SpringBoot 2.4.0 之后，spring.profiles被废弃，改用spring.config.activate.on-profile来声明这个文档块属于哪个环境。网上很多老教程还在用spring.profiles: dev的写法，低版本能用，但新项目再用就会报警告，而且高版本（2.4+）下不兼容。
切换环境还有两种常见方式。一是启动时手动指定：java -jar app.jar --spring.profiles.active=prod。二是直接用环境变量：SPRING_PROFILES_ACTIVE=prod java -jar app.jar。这两种方式优先级还高于配置文件里的spring.profiles.active，所以部署到服务器时不用改 jar 包里的任何东西，直接在启动脚本里指定即可，这才是真正意义上的"一次打包，到处运行"。
3.2 配置来源的覆盖顺序
这是全篇含金量最高的部分之一。你可能遇到过这种情况：本地跑起来一切正常，部署到服务器后配置文件不生效了，那种排查过程非常磨心态。要搞明白，就得清楚 SpringBoot 配置来源的优先级。从高到低大致是这样：
- 命令行参数（最高）：
java -jar app.jar --server.port=8081 - Java 系统属性：
java -Dserver.port=8081 -jar app.jar - 操作系统环境变量：
SERVER_PORT=8081 - jar 包外部的 application-{profile}.yml（和 jar 同目录的 config 子目录或同目录）
- jar 包外部的 application.yml
- jar 包内部的 application-{profile}.yml
- jar 包内部 application.yml（最低）
但这里有几个注意点。操作系统环境变量想表达server.port这种带点的层级结构，得改写成大写加下划线，也就是SERVER_PORT。SpringBoot 会把环境变量做宽松绑定，还能把下划线转成点。很多人第一次知道会觉得很神奇，但这是它兼容多平台的一种设计。
再补充一个细节：profile 相关配置和普通配置的优先级判定不一样。application-{profile}.yml的配置会覆盖application.yml中同名的普通配置，但它们都低于命令行参数。所以，假设你的application-prod.yml里写了server.port=8080，而命令行里甩过来--server.port=9090，最终生效的是 9090。这在排查"怎么我改了配置没生效"时是必须牢记的顺位关系。
3.3 配置优先级实战排查场景
说个真实发生过的案例。一个同事把 Redis 地址配在application-prod.yml里，然后气急败坏地找我说"生产环境怎么连的还是旧地址"。我一看部署脚本：
nohup java -jar app.jar --spring.profiles.active=prod &看起来没问题，环境也激活了。再往下查，服务器上/opt/app/config/目录下还放着一个application.yml，里面把spring.redis.host配成了旧地址。根据上面的优先级，jar 包外部的application.yml优先级高于 jar 包内部的application-prod.yml，于是生产环境读到了外部的旧地址。
这个案例说明：配置排查时，先判断配置来自哪个源，而不是先怀疑写错了。部署目录下的遗留文件、环境变量、启动脚本，这些都是容易被忽略的"隐藏配置源"。排查配置问题最快的路径就是把这几个位置的配置全部拉出来逐一比对。
4. 配置绑定与进阶技巧
4.1 @ConfigurationProperties 与宽松绑定
上一节讲了@ConfigurationProperties怎么用，这里深入讲一下它的"宽松绑定"特性。什么是宽松绑定？就是说，你用@ConfigurationProperties(prefix = "mall.jwt")绑定，配置文件里写mall.jwt.secret可以，写mall.jwt.secret下划线版本mall.jwt.secret-key也可以，甚至全大写MALL_JWT_SECRET也能被正确绑定。
这个特性让配置类能同时适配 properties、yml、环境变量三种配置来源。比如环境变量里表达mall.jwt.secret，你就得把它改写成MALL_JWT_SECRET、MALL_JWT_SECRETKEY这样的形式，SpringBoot 会自动进行规范化和匹配。
宽松绑定対 JavaBean 属性名的匹配遵循一个宽松规则：只要是字母、数字、下划线和连字符的排列，且去掉这些符号后能匹配上字段名，就算通过匹配。这个规则在重构字段名的时候要小心，一旦字段改名，旧的配置 key 可能依然能绑到新字段上，甚至出现配置了但绑错了字段的诡异问题。这种问题排查起来成本极高，所以配置字段名要尽量避免频繁改名。
4.2 随机值与占位符的实用套路
SpringBoot 配置支持生成随机数，这功能乍一听没什么用，但做单元测试和端口隔离时非常实用。用法如下：
server: port: ${random.int(10000, 19999)}随机数的完整列表包括${random.value}（随机字符串）、${random.int}、${random.long}、${random.uuid}。其中${random.uuid}可以拿来作为临时文件名前缀或者追踪 ID 值。这个我在写测试环境模拟数据时用得多，生产环境不建议把随机数用在路由或鉴权上，会让问题排查难上加难。
占位符同样很有用。它允许在配置 A 中引用配置 B 的值：
app: domain: example.com base-url: https://${app.domain}/api引用不存在的配置项，SpringBoot 启动会直接报错。如果你希望某个引用取不到时给它一个兜底值，就加个冒号写默认值：
app: base-url: ${app.domain:localhost}/api这些写法干净利落，但要注意别用出高耦合。像${app.domain}这种同一个 key 被多个地方引用时，它就是全项目配置的统一入口，本身没问题；但如果一个组件的配置强依赖另一个组件的内部变量，就要考虑是不是该抽成一个独立的配置类来管理了。
4.3 敏感信息处理的正确姿势
配置里最刺眼的往往是密码、密钥。直接明文写在application.yml里，上传到 Git，等于把钥匙插在锁上递给所有人。我见过不少团队把生产数据库密码直接打在配置里，等出了问题才追悔莫及。
三个办法可以组合使用。
第一，用环境变量替代明文。比如：
spring: datasource: password: ${DB_PASSWORD}在服务器启动脚本里提前 export 环境变量，Git 仓库里永远不会出现真实密码。
第二，用配置中心。Nacos、Apollo 这类配置中心天然支持配置的权限控制、版本管理和动态刷新。敏感配置放在配置中心，只在应用里留一个 bootstrap 引导配置，能有效收敛密钥泄露面。
第三，本地加密。Jasypt 整合 SpringBoot 可以对配置项做加解密，配置里存的是密文，运行期解密。这个方案在引入时会有性能和运维成本，但比起密码裸奔还是值得的。我自己的倾向是：小项目用环境变量方案最省事，中大型项目直接上配置中心。
5. 常见问题与排查技巧实录
5.1 配置没生效的排查思路
"我配置了为什么没效果"是 SpringBoot 问题区的日经话题。真遇到时，按下面的顺序排查，基本 5 分钟内能锁定原因：
- 先确认配置文件的命名。必须是
application.yml或application.properties，多环境的是application-{profile}.yml。拼写错一个字母，SpringBoot 根本找不到，就只能用默认值了。这种错误隐蔽性很高，因为项目能启动，只是配置全没读进去。 - 确认配置文件的位置。SpringBoot 默认从 classpath 根路径读
application.yml。如果你把配置文件放到了别的目录但没指定spring.config.location，那它就只是一个普通文件，不会参与配置加载。 - 确认 profile 是否激活。在启动日志里搜
The following profiles are active，如果显示的 profile 不是你想用的，说明spring.profiles.active没配好，或者启动命令里的参数没传对。 - 确认有没有多个配置源覆盖。这个就看第 3 章优先级的内容。命令行、环境变量、外部文件，一层层剥开看到底是谁覆盖了谁。
始终记住一条核心原则：SpringBoot 的配置体系是按优先级覆盖的，不存在"我加了一句配置就应该生效"这种理所当然。所有配置最终都合并成同一个 Environment 对象，归属它的 runner 决定最终取值。
5.2 类型转换与格式踩坑实录
YAML 对类型很敏感。举个例子，以下几个写法是不同的：
server: port: 8080 # 整数 port: "8080" # 字符串 port: 08080 # 数字，但会按八进制解析，直接报错端口号写成带引号的字符串，SpringBoot 还能自动转成整数；但你要是手滑写了个08080，YAML 会把开头是 0 的数字当八进制解析，运行时直接转换失败。这种错误报错信息往往很隐晦，看起来是"端口配置无法解析"，实际是 YAML 解析阶段就出了问题。
properties 文件也有自己的坑。中文注释和中文配置值要用 UTF-8 编码保存，Windows 环境下不小心用了 GBK 编码，启动时会出现乱码，严重时直接解析报错。IDEA 里可以在Settings -> Editor -> File Encodings把 properties 文件强制设为 UTF-8，顺手把"Transparent native-to-ascii conversion"勾上。
5.3 多环境配置失效的典型场景
场景一是同一配置项出现在多个 profile 文件里，但激活的环境不对。这种情况下的表现是：本地好好的，测试环境也用得正常，偏偏生产环境用了一个"老配置"。排查思路同 5.1，先看The following profiles are active，再用配置优先级判断是谁覆盖了谁。
场景二是同一配置项在主 application.yml 和 profile 文件里都有。这时 profile 文件的优先级更高。假设你在主文件里配了server.port=8080，application-prod.yml里配了server.port=7070，激活 prod 后实际端口是 7070。理解这个规则后，你就不会因为"主文件明明改了端口，生产却没变"而抓瞎了。
场景三是手动指定spring.config.location导致多环境机制失效。一旦显式指定了配置文件路径，application-{profile}这套约定自动失效。这时候你的 profile 配置就再也不被加载，但项目照样启动，只是所有环境相关的配置全部缺失。这类问题最阴险，因为它不会给你报错。
配置管理这件事的心态分享
坦白说，写实话说，配置这块想一次记全很难，我当初也是踩了无数坑才慢慢建立起体系化理解的。你想少走弯路的话，我的建议很简单：项目初始化时，花一点时间把配置按"基础配置、环境配置、公共业务配置、敏感配置"四类拆清楚，对应放到不同的 profile 或配置中心。你会发现后续每次加配置、换环境都轻松很多，不用每次上线都像在拆弹。
还有一个我坚持了很久的习惯：每次配置一个之前没接触过的属性时，先写个小测试验证它确实生效了，再提交代码。这个习惯看似多此一举，但能拦住大量的"假生效"问题。配置文件不像 Java 代码，没有编译器帮你检查，保持一点谨慎，省出来的是半夜排查事故的时间。
