多环境配置这件事，几乎每个用 Spring Boot 做项目的团队都会撞上。最早大家都是把所有配置往一个application.yml里塞，本地开发、测试环境、预发、生产全混在一起，改一行配置心惊胆战，提交代码前还得反复确认有没有把本地数据库地址带上去。后来大家开始用application-{profile}.yml拆分，情况好了一些，但新的问题又冒出来：打包的时候到底激活哪个 profile？怎么保证打出来的 jar 在目标环境里跑的就是对应那套配置？Maven 的 profile 和 Spring 的 profile 名字对不上怎么办？这篇文章就围绕“用 Maven 多环境构建来动态启用 Spring Boot 的 Profiles”这条主线，把文件拆分、构建参数注入、资源过滤、打包验证这一整套流程拆开讲清楚。适合已经能跑起 Spring Boot 项目、但被多环境配置折腾过的同学，也适合刚接手一个配置混乱的老项目、想动手整理的人。下面这些内容都是我在实际项目里反复调整后沉淀下来的做法，能直接照着复现。
1. 整体设计思路与方案选型拆解
1.1 为什么不能只靠 Spring 的 profile 机制
先把这个问题的本质说清楚。Spring Boot 的 profile 机制解决的是“运行时加载哪套配置”，它通过spring.profiles.active这个属性来决定激活哪些配置文件。但这里有个关键点：这个属性本身也得有个地方写。如果写死在application.yml里，那打包出来的产物就绑死了某个环境；如果靠启动命令--spring.profiles.active=prod传，那部署脚本就得记住每个环境该传什么，一旦漏传或者传错，应用可能带着开发库的配置跑在生产上，这种事故我见过不止一次。
所以真正要解决的是两层问题：第一层是配置文件按环境拆开，让每套配置独立可维护；第二层是构建阶段就把目标环境确定下来，让打出来的包自带正确的 profile 激活信息，部署时不需要人工干预。Maven 的 profile 机制正好补上第二层，它能在构建时根据传入的参数决定打包行为，包括往产物里写入哪个 profile 标识。两层机制各管一段，职责清晰，这是整个方案能站得住脚的根基。
1.2 文件拆分的粒度怎么定
拆分配置文件不是越细越好。我见过有人把数据源、缓存、消息队列、日志各拆一个文件，最后application.yml里一堆spring.config.import，维护成本反而上去了。比较务实的做法是按“环境”这个维度拆，也就是application-dev.yml、application-test.yml、application-prod.yml这种，每个文件里放该环境下的全部差异配置。公共配置留在application.yml里，比如应用名、端口、序列化规则这些不随环境变化的东西。
这样拆的好处是，看一个文件就能知道某个环境的全貌，排查问题时不用在多个文件之间跳。代价是每个环境文件里会有一些重复的键，但这个重复是可接受的，因为环境之间的差异本来就该显式表达出来，而不是靠继承关系去猜。至于更细的维度，比如按业务模块拆，我建议等配置量真的到了几百行的规模再考虑，早期没必要给自己加复杂度。
1.3 Maven profile 与 Spring profile 的对应关系
这里有个容易混淆的点：Maven 的 profile 和 Spring 的 profile 是两套独立的东西，名字可以一样也可以不一样，但为了可维护性，我强烈建议让它们保持一致。Maven profile 的 id 用dev、test、prod，Spring 的 profile 也用同样的名字，这样从构建命令到运行时日志，整个链路上的标识是统一的，排查问题时不会出现“Maven 里叫 production、Spring 里叫 prod”这种对不上的情况。
对应关系的实现方式是在 Maven profile 里定义一个属性，比如spring.profiles.active，然后在资源过滤时把这个属性值写进配置文件。这样构建时-P prod就会让产物里的激活标识变成prod。整个链路是：Maven 参数决定 Maven profile，Maven profile 决定属性值，属性值经过资源过滤写进配置文件，Spring 启动时读取配置文件里的标识。每一环都可追踪，出问题能快速定位是哪一环没对上。
1.4 方案对比：资源过滤 vs 多套配置文件目录
实现动态启用还有另一种常见做法：为每个环境准备一套完整的配置目录，构建时通过 Maven 的资源插件把对应目录复制到target/classes。这种做法的优点是环境之间完全隔离，缺点是公共配置要复制多份，改一个公共项得改好几个地方，容易漏。
资源过滤的做法是只维护一份application.yml模板，里面用占位符表示会变化的部分，构建时替换。它的优点是公共配置只有一份，缺点是占位符语法如果和配置文件本身的语法冲突（比如 YAML 里的${}有时会被 Spring 自己解析），需要小心处理。我最终选的是资源过滤，因为配置项重复带来的维护成本在长期看更高，而占位符冲突的问题可以通过约定命名规则来规避，比如统一用@...@这种 Maven 默认的过滤分隔符，避免和 Spring 的${}撞车。
2. 核心配置细节与实操要点
2.1 目录结构怎么摆
先看落地后的目录结构，这是后面所有操作的基础。标准做法是把环境配置文件放在src/main/resources下，和主配置文件平级：
src/main/resources/ ├── application.yml ├── application-dev.yml ├── application-test.yml └── application-prod.ymlapplication.yml里只放公共配置和 profile 激活的占位符，各环境文件放差异配置。这里有个细节要注意：application.yml里的spring.profiles.active用占位符写，构建时被替换；而各环境文件里不要再写spring.profiles.active，否则会出现自己激活自己的混乱情况。我见过有人在application-prod.yml里又写了一遍spring.profiles.active: prod，虽然多数情况下不报错，但语义上是冗余的，容易让人误以为这里才是激活入口。
2.2 主配置文件里的占位符写法
application.yml的关键片段大概是这样：
spring: application: name: demo-service profiles: active: @spring.profiles.active@这里的@spring.profiles.active@就是 Maven 资源过滤的占位符。用@...@而不是${...}的原因是，Spring 自己在解析 YAML 时也会处理${}，两者混在一起容易出现“到底是谁替换的”这种困惑。Maven 的资源过滤默认支持@...@分隔符（较新版本的 maven-resources-plugin 默认开启），用它可以和 Spring 的占位符彻底分开，减少踩坑。
需要确认的是pom.xml里资源过滤是否开启。默认情况下src/main/resources的资源过滤是关闭的，必须显式配置：
<build> <resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> </resource> </resources> </build>注意：开启过滤后，
src/main/resources下所有文件里的@...@都会被替换。如果项目里有二进制文件或者不该被过滤的模板文件，要用<excludes>排除，否则可能把文件内容改坏。
2.3 Maven profile 的定义方式
在pom.xml里定义三个 profile，每个负责设定spring.profiles.active的值：
<profiles> <profile> <id>dev</id> <properties> <spring.profiles.active>dev</spring.profiles.active> </properties> <activation> <activeByDefault>true</activeByDefault> </activation> </profile> <profile> <id>test</id> <properties> <spring.profiles.active>test</spring.profiles.active> </properties> </profile> <profile> <id>prod</id> <properties> <spring.profiles.active>prod</spring.profiles.active> </properties> </profile> </profiles>dev设为默认激活，这样本地直接mvn package不用带参数也能跑，符合开发时的习惯。test和prod必须显式指定，避免误打包。这里属性名用spring.profiles.active是刻意的，它和 Spring 的属性名一致，读配置的人一眼能明白这个属性最终流向哪里。
2.4 环境文件里的差异配置示例
以数据源为例，application-dev.yml和application-prod.yml的差异大概是这样：
# application-dev.yml spring: datasource: url: jdbc:mysql://127.0.0.1:3306/demo_dev?useUnicode=true username: dev_user password: dev_pass logging: level: root: debug# application-prod.yml spring: datasource: url: jdbc:mysql://db-host:3306/demo_prod?useUnicode=true username: prod_user password: ${DB_PASSWORD} logging: level: root: info生产环境的密码用环境变量占位，不写死在文件里，这是基本的安全习惯。开发环境可以写明文方便调试，但也要注意别把真实的生产凭据提交到代码库。这种差异配置的写法让每个环境的全貌一目了然，改配置时目标明确。
2.5 资源过滤的排除规则
前面提到要排除不该过滤的文件。实际项目里常见需要排除的有：字体文件、图片、证书、以及一些第三方库要求的二进制资源。配置方式：
<resource> <directory>src/main/resources</directory> <filtering>true</filtering> <excludes> <exclude>**/*.png</exclude> <exclude>**/*.jpg</exclude> <exclude>**/*.ttf</exclude> <exclude>**/*.p12</exclude> </excludes> </resource>这个排除列表要根据项目实际情况维护。我踩过的坑是漏排了一个.p12证书文件，过滤后文件损坏，启动时报证书解析失败，排查了半天才定位到是资源过滤干的。所以凡是二进制文件，一律排除，宁可多排不要漏排。
3. 完整构建流程与验证方法
3.1 构建命令与参数传递
日常构建分三种场景，命令各不相同：
# 本地开发，走默认 dev profile mvn clean package # 打测试环境包 mvn clean package -P test # 打生产环境包 mvn clean package -P prod-P后面跟的是 Maven profile 的 id。这里要注意，如果同时激活多个 profile，后定义的属性会覆盖先定义的，容易出意外，所以构建脚本里应该明确只传一个。CI 流水线里建议把 profile 作为必填参数，不传就报错退出，避免默认值把生产包打成开发包。
3.2 验证产物里的 profile 是否正确
打包完成后，别急着部署，先验证产物里的配置对不对。最直接的办法是解压 jar 看application.yml：
unzip -p target/demo-service.jar BOOT-INF/classes/application.yml | grep -A2 "profiles"期望看到active: prod这样的输出。如果看到的是占位符原文@spring.profiles.active@，说明资源过滤没生效，回去检查pom.xml里的<filtering>true</filtering>是否配置在正确的 resource 上。如果看到的是dev，说明-P prod没传对或者 profile id 拼错了。
这个验证步骤看起来简单，但能拦住大部分构建配置问题。我习惯把它写进 CI 的构建后检查里，用脚本自动比对，不通过就中断流水线，避免带错配置的包流到部署环节。
3.3 启动时的日志确认
应用启动后，日志里会打印当前激活的 profile，类似The following 1 profile is active: "prod"。这是运行时的最终确认。如果这里显示的和预期不符，说明配置文件里的激活标识没写对，或者启动命令里又用--spring.profiles.active覆盖了。后者是常见的“双重指定”问题：构建时写进了配置文件，部署脚本里又传了启动参数，两者不一致时启动参数优先级更高，结果就是构建时的努力白费。所以部署脚本里不要再传 profile 参数，让产物自己决定。
3.4 多模块项目的处理
如果项目是多模块的，资源过滤的配置要放在需要过滤的那个模块的pom.xml里，而不是父 pom。父 pom 里定义 profiles 和属性，子模块里配置资源过滤，这样职责清晰。我见过把资源过滤配在父 pom 的<build>里，结果所有子模块都被过滤，某个子模块的模板文件被改坏的情况。多模块场景下，只给真正需要写 profile 标识的模块开启过滤，其他模块保持默认。
3.5 打包产物的命名区分
不同环境的包最好在文件名上就能区分，避免部署时拿错。可以在pom.xml的<finalName>里带上 profile 信息：
<build> <finalName>${project.artifactId}-${spring.profiles.active}</finalName> </build>这样打出来的包叫demo-service-prod.jar，一眼能看出是哪个环境的。这个小改动在多人协作、多环境并行部署时特别有用，能省掉不少“这个包是哪个环境的”这种确认成本。
4. 常见问题排查与避坑经验
4.1 占位符没被替换的几种原因
这是最高频的问题。表现是产物里的application.yml还带着@spring.profiles.active@原文。原因通常有三个：一是资源过滤没开启，检查<filtering>true</filtering>；二是占位符分隔符不匹配，如果项目用的老版本插件只认${}，那@...@就不会被替换，需要确认插件版本或者改用${}并处理好与 Spring 的冲突；三是文件不在被过滤的 resource 目录下，比如放在了src/main/resources/config/子目录但 resource 配置只覆盖了根目录。逐个排查基本能定位。
4.2 profile 激活了但配置没生效
有时候日志显示激活了prod，但连的还是开发库。这种情况多半是环境文件名和 profile 名对不上，比如 profile 叫prod，文件却叫application-production.yml，Spring 找不到对应文件就只用主配置。命名必须严格一致，application-{profile}.yml里的{profile}就是激活的标识。另一个可能是环境文件放在了错误的目录，比如放到了src/main/resources/config/下，而 Spring Boot 默认的搜索路径虽然包含config子目录，但优先级和预期可能不同，建议统一放在resources根下。
4.3 敏感配置泄露的风险
资源过滤会把属性值写进产物，如果属性值里包含密码，那密码就明文躺在 jar 里了。所以生产环境的敏感项一律用环境变量占位，比如${DB_PASSWORD}，构建时不替换，运行时由部署环境注入。这里要注意，${DB_PASSWORD}这种写法在 YAML 里会被 Spring 解析，属于运行时占位，和 Maven 的构建时占位是两回事，不要混淆。构建时占位用@...@，运行时占位用${...}，两者分工明确。
4.4 常见问题速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 产物里是占位符原文 | 资源过滤未开启或分隔符不匹配 | 检查 filtering 配置和插件版本 |
| 激活了 profile 但配置没生效 | 文件名与 profile 名不一致 | 核对application-{profile}.yml命名 |
| 启动参数覆盖了构建配置 | 部署脚本传了--spring.profiles.active | 移除启动参数，让产物决定 |
| 二进制文件损坏 | 资源过滤误伤了非文本文件 | 在 excludes 里补充排除规则 |
| 多模块下部分模块配置异常 | 过滤配置放在了父 pom | 移到需要过滤的子模块 |
4.5 实操心得：先小步验证再全量铺开
这套方案涉及 Maven 和 Spring 两层机制，一次性全改容易出问题。我的建议是先在一个模块或者一个简单项目上跑通完整链路：拆分文件、配好 profile、打包、解压验证、启动确认。链路通了再往多模块、往老项目上迁移。迁移时优先处理数据源和日志这两类配置，因为它们最容易出环境差异问题，也最容易验证效果。等这两类稳定了，再逐步把其他配置项挪进环境文件。
另外一个小技巧：在application.yml里保留一份“兜底”的公共配置，环境文件只覆盖差异项。这样即使某个环境文件漏了某个键，应用也能用兜底值启动，不至于直接起不来。当然，兜底值要选安全的默认值，比如指向本地地址而不是生产地址，避免漏配时误连。
5. 与 CI 流水线的衔接要点
5.1 把 profile 作为流水线参数
在持续集成环境里，构建任务应该把 profile 作为显式参数暴露出来，由触发构建的人或者上游任务指定。参数校验要做，只允许dev、test、prod这几个白名单值，传其他值直接失败。这样能防止手误传错导致打错包。构建命令里-P后面跟的就是这个参数，整个链路从流水线参数到 Maven profile 到产物配置一气呵成。
5.2 构建后自动校验
前面提到的解压验证可以脚本化，放在构建步骤之后、制品归档之前。脚本逻辑是：解压产物里的application.yml，提取spring.profiles.active的值，和传入的参数比对，不一致就退出非零码让流水线失败。这个检查成本很低，但能拦住绝大多数配置错误，值得每个项目都加上。
5.3 制品命名与归档
制品归档时文件名带上 profile 标识，配合前面说的<finalName>配置，归档后的包名自带环境信息。这样在制品仓库里一眼能区分不同环境的包，回滚时也不会拿错。如果制品仓库支持元数据，还可以把 profile 作为元数据字段存进去，方便检索。
5.4 部署环节的配合
部署脚本里不要再传--spring.profiles.active，让产物自己决定。如果部署平台强制要求传启动参数，那要确保传的值和产物里的一致，并且以产物为准做校验。最稳妥的做法是部署前先读产物里的 profile 值，再决定部署到哪个环境，形成闭环。这样即使有人手动改了包，部署环节也能发现不一致并拦截。
6. 配置演进与长期维护建议
6.1 配置项该放哪一层
随着项目演进，配置项会越来越多，这时候要有明确的归属规则。我的规则是：不随环境变化的放application.yml，随环境变化的放环境文件，敏感信息用环境变量。判断标准很简单，问一句“这个值在测试环境和生产环境一样吗”，答案是否就放环境文件。这条规则能覆盖绝大多数情况，减少“这个配置该放哪”的纠结。
6.2 环境文件的评审机制
环境文件里的改动应该走代码评审，尤其是生产环境文件。因为一个配置错误可能直接导致线上故障，评审时重点关注数据源地址、超时时间、开关类配置。我见过把限流开关误改成关闭导致线上被打挂的案例，评审能拦住这类低级错误。评审时还可以对比不同环境文件的差异，确认差异都是有意为之。
6.3 定期清理无用配置
项目跑久了，环境文件里会积累一些已经废弃的配置项，比如已经下线的功能对应的开关。这些无用配置不仅增加维护负担，还可能误导后来的人。建议每个季度做一次配置清理，对照代码里的实际使用情况，把没人读的键删掉。清理前先在测试环境验证，确认删除不影响启动和功能。
6.4 新成员的上手引导
这套机制对新人来说有一定理解成本，尤其是 Maven profile 和 Spring profile 两层的关系。建议在项目文档里写清楚：构建命令怎么传参、产物怎么验证、配置该放哪一层。文档不用长，把关键链路画清楚就行。新人第一次打包时带着走一遍完整流程，比看文档更有效。
7. 几个容易被忽略的细节
7.1 IDEA 里的运行配置
在本地用 IDEA 跑应用时，IDEA 会用自己的方式处理资源，可能不经过 Maven 的资源过滤。这时候application.yml里的@spring.profiles.active@不会被替换，启动会报错或者激活失败。解决办法是在 IDEA 的运行配置里把spring.profiles.active作为环境变量或者 VM 参数传进去，绕开占位符。或者干脆在本地开发时用一个不带占位符的配置，打包时才用模板。这个细节很多人第一次搭这套机制时会卡住，提前知道能省不少时间。
7.2 测试代码里的配置加载
单元测试和集成测试加载配置的方式和生产不同，如果测试里依赖了application.yml的占位符，可能因为没经过 Maven 过滤而失败。测试场景建议用@ActiveProfiles注解显式指定 profile，或者用测试专用的配置文件，不要依赖构建时的占位符替换。测试配置和构建配置分开管理，互不干扰。
7.3 配置文件的编码问题
资源过滤时如果文件编码和插件配置的编码不一致，中文注释可能变成乱码。确保pom.xml里配置了<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>，并且资源插件的编码也设为 UTF-8。这个坑在配置文件里有中文注释时才会暴露，容易被忽略，但一旦出现排查起来很费劲。
7.4 版本升级时的兼容性
Maven 资源过滤的默认分隔符在不同版本的插件里有差异，老版本默认只认${}，新版本才默认支持@...@。升级构建插件版本时要注意这个变化，升级后跑一遍完整构建验证产物。如果项目里同时有${}和@...@两种占位符，升级后可能出现意外的替换行为，升级前先梳理清楚占位符的使用情况。
这套机制搭好之后，日常开发基本感觉不到它的存在，打包传个参数就行，配置各归各位，部署时不用再操心激活哪个 profile。真正体现价值的时候是出问题的时候：配置错了能快速定位是哪一层的问题，产物验证能拦住带错配置的包，评审能拦住危险的改动。我在几个项目里推行这套做法后，因为配置问题导致的部署事故基本归零，这大概就是前期多花点时间把机制理顺的回报。后续如果配置规模继续膨胀，可以考虑引入配置中心，把环境差异从文件里挪到中心化管理，但那是另一个话题了，在配置量还没到那个程度之前，Maven 加 Spring 的这套组合足够用，也足够稳。
