写配置文件的文章很多但大多绕来绕去真正能帮你把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.port8080。application.yml则是随着 Spring 生态发展被引入的使用 YAML 格式靠缩进表达层级关系。两边其实都能完成同样的配置任务语言层面的区别主要在这几点可读性层级少的时候 properties 看着干净层级一多比如spring.datasource.hikari.connection-timeoutproperties 的 key 会变得很长yml 用缩进表达从属关系逻辑上更像一棵树。类型表达YAML 天然支持集合、Map、布尔值、数字类型写起来直观properties 全是字符串虽然 SpringBoot 最终也会做类型转换但写起来繁琐。多环境支持单个 yml 可以用---分隔多个文档块在一个文件里模拟多个 profileproperties 必须拆多个文件后面细讲。容错性properties 更宽容错了也不太影响整体解析yml 对空格缩进极其敏感一个缩进错误整个文件直接解析失败报错还特别难懂。我的做法是新项目优先用 yml因为可读性好、层级清晰团队协作时 diff 也更友好如果项目里已经有大量 properties 文件或者你的团队对 YAML 缩进实在不敏感总有同事把空格对齐搞砸老老实实用 properties 反而少操一份心。这没有哪个更好只有哪个更适合你们的团队。2. 核心配置项逐项拆解与实操2.1 服务端口与上下文路径先聊聊最基础但最容易出问题的部分。配置服务的端口和路径在 properties 里是这样写server.port8080 server.address0.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.port0端口设为 0 时SpringBoot 会随机找一个可用端口启动。这在单测里很常见但你得从ServletWebServerApplicationContext里拿到实际端口否则测试根本打不进去。这个技巧在日常业务开发里用得少不过面试问到SpringBootTest的端口隔离原理时能派上用场。2.2 数据库与连接池配置数据库配置是配置文件的重头戏。拿最常见的 MySQL 举例spring: datasource: url: jdbc:mysql://localhost:3306/mall?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/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否则绑定不上。如果你用的是 LombokData就能解决。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.activedev在 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.activeprod。二是直接用环境变量SPRING_PROFILES_ACTIVEprod java -jar app.jar。这两种方式优先级还高于配置文件里的spring.profiles.active所以部署到服务器时不用改 jar 包里的任何东西直接在启动脚本里指定即可这才是真正意义上的一次打包到处运行。3.2 配置来源的覆盖顺序这是全篇含金量最高的部分之一。你可能遇到过这种情况本地跑起来一切正常部署到服务器后配置文件不生效了那种排查过程非常磨心态。要搞明白就得清楚 SpringBoot 配置来源的优先级。从高到低大致是这样命令行参数最高java -jar app.jar --server.port8081Java 系统属性java -Dserver.port8081 -jar app.jar操作系统环境变量SERVER_PORT8081jar 包外部的 application-{profile}.yml和 jar 同目录的 config 子目录或同目录jar 包外部的 application.ymljar 包内部的 application-{profile}.ymljar 包内部 application.yml最低但这里有几个注意点。操作系统环境变量想表达server.port这种带点的层级结构得改写成大写加下划线也就是SERVER_PORT。SpringBoot 会把环境变量做宽松绑定还能把下划线转成点。很多人第一次知道会觉得很神奇但这是它兼容多平台的一种设计。再补充一个细节profile 相关配置和普通配置的优先级判定不一样。application-{profile}.yml的配置会覆盖application.yml中同名的普通配置但它们都低于命令行参数。所以假设你的application-prod.yml里写了server.port8080而命令行里甩过来--server.port9090最终生效的是 9090。这在排查怎么我改了配置没生效时是必须牢记的顺位关系。3.3 配置优先级实战排查场景说个真实发生过的案例。一个同事把 Redis 地址配在application-prod.yml里然后气急败坏地找我说生产环境怎么连的还是旧地址。我一看部署脚本nohup java -jar app.jar --spring.profiles.activeprod 看起来没问题环境也激活了。再往下查服务器上/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 还能自动转成整数但你要是手滑写了个08080YAML 会把开头是 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.port8080application-prod.yml里配了server.port7070激活 prod 后实际端口是 7070。理解这个规则后你就不会因为主文件明明改了端口生产却没变而抓瞎了。场景三是手动指定spring.config.location导致多环境机制失效。一旦显式指定了配置文件路径application-{profile}这套约定自动失效。这时候你的 profile 配置就再也不被加载但项目照样启动只是所有环境相关的配置全部缺失。这类问题最阴险因为它不会给你报错。配置管理这件事的心态分享坦白说写实话说配置这块想一次记全很难我当初也是踩了无数坑才慢慢建立起体系化理解的。你想少走弯路的话我的建议很简单项目初始化时花一点时间把配置按基础配置、环境配置、公共业务配置、敏感配置四类拆清楚对应放到不同的 profile 或配置中心。你会发现后续每次加配置、换环境都轻松很多不用每次上线都像在拆弹。还有一个我坚持了很久的习惯每次配置一个之前没接触过的属性时先写个小测试验证它确实生效了再提交代码。这个习惯看似多此一举但能拦住大量的假生效问题。配置文件不像 Java 代码没有编译器帮你检查保持一点谨慎省出来的是半夜排查事故的时间。