Spring Boot profile 多环境配置完整指南

理解 profile 组织方式、激活来源、覆盖规则和团队协作建议。

撰写与维护： ErickPang · 更新于： 2026-07-10

说明 dev、test、prod 等 profile 的配置组织方式、激活顺序、覆盖规则和常见排错方法。

profile 解决什么问题

Spring Boot profile 用来区分不同环境下的配置，例如本地开发、测试环境、预发布和生产环境。共同配置放在 application.yml 或 application.properties 中，环境差异放在 application-dev.yml、application-test.yml 或 application-prod.yml 中。

这样做的目标不是让文件变多，而是减少互相污染。开发环境可以使用本地数据库和更详细的日志，生产环境则应使用受控的数据源、较保守的日志级别和明确的暴露端点。

spring:
  profiles:
    active: dev

# application-dev.yml
server:
  port: 8081
logging:
  level:
    root: DEBUG

激活顺序和覆盖规则

配置不生效时，最容易忽略的是激活来源。profile 可以通过配置文件、命令行参数、环境变量或部署平台注入。后加载或更高优先级的来源可能覆盖你在文件里看到的值。

排查时建议先打印当前 active profiles，再确认同一个 key 在基础文件和 profile 文件中的最终值。不要只看一个文件就判断应用正在使用哪个配置。

启动日志通常会输出当前 active profiles
命令行参数可能覆盖配置文件中的 active profile
环境变量可能来自 CI/CD 或容器平台
同一配置键在 profile 文件中会覆盖基础文件

团队协作建议

团队项目不要把个人本地配置直接写进共享 profile。可以提供 application-local.yml 示例，但真实密码、私有地址和个人端口应通过本地未提交文件或环境变量管理。

对生产 profile 做代码评审时，重点检查 datasource、logging、management endpoints 和安全相关配置。它们出错的影响通常比普通业务开关更大。

选择明确的激活入口

开发机可以在 IntelliJ IDEA Run Configuration 中设置 SPRING_PROFILES_ACTIVE=dev，部署环境则由容器、启动脚本或平台注入 prod。这样能够避免为了切换环境反复修改并提交 application.yml。

spring.profiles.active 和 spring.profiles.default 只能出现在非 profile 专用文档中，不能写进 application-prod.yml，也不能放在通过 spring.config.activate.on-profile 激活的文档里。违反这一限制时，不应通过调整文件顺序规避，而应把激活入口移回基础配置或启动环境。

# IntelliJ IDEA environment variable
SPRING_PROFILES_ACTIVE=dev

# command line
java -jar app.jar --spring.profiles.active=prod

用 profile group 管理组合环境

当 production 同时需要 proddb、prodmq 和 observability 等多个细分 profile 时，可以使用 profile group。调用方只激活 production，具体组合留在基础配置中维护，避免每个部署脚本重复一长串 profile 名称。

group、include 和 active 都受 PropertySource 覆盖规则影响。修改组合后，应从启动日志确认实际 active profiles，并验证数据源、消息队列和监控配置是否来自预期文件。

spring:
  profiles:
    group:
      production:
        - proddb
        - prodmq
        - observability

排查资料与相关文章

排查顺序应固定为：确认启动入口、读取 active profiles、搜索重复 key、核对外部配置位置、最后验证运行值。Spring Boot 官方 Profiles 文档说明了 active、default、include 和 group 的限制；更完整的覆盖顺序在 Externalized Configuration 文档中维护。

本站由 ErickPang 独立维护，与 Spring、JetBrains 或 Broadcom 无官方关联。