在同一套 Spring Boot 代码里，开发环境要用本机 MySQL 和 8080 端口，测试环境要连内网测试库，生产环境要连高可用数据库并开启严格日志。最初的做法可能是维护多份配置文件，切换环境时手动改名或修改参数，一旦发布流程紧张，很容易把开发配置带进生产。Spring Boot 的 Profile 机制正是为这种场景设计的，它用逻辑名称把不同环境的配置隔离开，让同一份构建产物可以在不同环境加载不同配置，而不需要修改代码或配置文件本身。

Profile 并不是一个独立的配置中心，而是 Spring 容器在启动阶段用来筛选配置源和 Bean 的条件标记。理解它的工作方式，才能避免多环境切换时出现误连数据库、配置不生效、Bean 装配错误等问题。下面从加载机制、文件组织、激活方式、条件装配和实际避坑几个角度展开。

一、Profile 的本质与配置加载过程

Spring Boot 启动时会把所有符合条件的配置文件读入 Environment，包括 application.yml、application-dev.yml 等。Profile 并不是一个新的配置文件格式，而是一种过滤条件。比如 application-dev.yml 本身就代表 dev 这个 Profile，只有 active profiles 包含 dev 时，这个文件才会被解析进 PropertySource。这个机制与 @Profile 注解类似，后者控制 Spring 容器是否创建某个 Bean。

加载顺序上，Spring Boot 先读取主配置 application.yml，再读取与 active profiles 匹配的 application-{profile}.yml。同名属性后者会覆盖前者。例如 application.yml 里配置了 server.port: 8080，application-prod.yml 里配置 server.port: 8443，当激活 prod 时最终端口是 8443。这个覆盖顺序让公共配置和差异配置可以分层维护。

需要特别注意，只有被激活的 Profile 文件才会参与属性覆盖。如果 application-prod.yml 没有被激活，它的内容完全不会进入 Environment，也就不会影响应用启动。这种按需加载的特性，使得同一份代码包可以在多套环境中安全复用。

二、文件拆分与 YAML 多文档的配置实践

最推荐的做法是按环境拆分文件。例如项目 resources 下放置 application.yml 基础配置，再放 application-dev.yml、application-test.yml、application-prod.yml。主配置只需要声明默认激活哪个环境，或者干脆不声明，交给部署平台注入。这样每个环境差异清晰，文件量不大。

# application.yml
spring:
  application:
    name: order-service
  profiles:
    active: dev
  datasource:
    hikari:
      maximum-pool-size: 20
# application-dev.yml
server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/order_db?useSSL=false&serverTimezone=UTC
    username: root
    password: dev123
logging:
  level:
    com.example.order: debug
# application-prod.yml
server:
  port: 8443
spring:
  datasource:
    url: jdbc:mysql://10.20.30.40:3306/order_db?useSSL=false
    username: prod_user
    password: prod_pass
logging:
  level:
    com.example.order: info

如果不想把配置拆散成多个文件，也可以用 YAML 多文档块，在一个文件里用三个短横线分隔不同文档，并通过 spring.config.activate.on-profile 指定该段配置属于哪个 Profile。这种方式更适合配置较短、环境差异不大的项目。需要注意，多文档的优先级同样由 active profiles 决定，没有激活的文档不会生效。

spring:
  application:
    name: order-service
  profiles:
    active: dev
---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 8080
---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 8443

两种方式可以混用，但建议团队统一。文件拆分更容易做权限隔离，比如生产配置放入独立的 git 仓库或仅由运维维护；YAML 多文档则减少文件数量，但所有环境配置集中在一个文件里，稍不注意容易改错段。无论选择哪种，都要保证生产环境的关键信息不会随着公共仓库泄露。

三、激活 Profile 的多种方式与优先级

激活 Profile 至少有五种方式。第一种是写在主配置文件里，例如 spring.profiles.active: dev。第二种是启动命令行参数，java -jar app.jar --spring.profiles.active=prod。第三种是环境变量，export SPRING_PROFILES_ACTIVE=prod，Spring Boot 会自动把它映射为 spring.profiles.active 属性。第四种是 JVM 参数，java -Dspring.profiles.active=prod -jar app.jar。第五种是在 main 方法里通过 SpringApplication.setAdditionalProfiles 设置，但这种方式优先级较低，更多用于测试。

优先级遵循 Spring Boot 的属性源顺序：命令行参数高于环境变量，环境变量高于主配置文件，主配置文件高于代码默认值。比如 application.yml 里写 dev，环境变量又设置为 prod，最终生效的是 prod。理解这一点很关键，很多所谓配置不生效的问题，其实是更高优先级来源覆盖了预期值。建议部署时统一用环境变量或部署平台提供的配置中心注入，而不是在代码和命令行里随意设置。

# 命令行参数方式
java -jar order-service.jar --spring.profiles.active=prod
# JVM 参数方式
java -Dspring.profiles.active=prod -jar order-service.jar
# 环境变量方式，Linux 或 macOS
export SPRING_PROFILES_ACTIVE=prod
java -jar order-service.jar
# Windows PowerShell 方式
$env:SPRING_PROFILES_ACTIVE="prod"
java -jar order-service.jar

在 IDE 或 Maven 命令里也可以传递参数。使用 spring-boot:run 时，mvn spring-boot:run -Dspring-boot.run.profiles=prod 比 -Dspring.profiles.active=prod 更可靠，因为后者有时不会传给 forked JVM。这个细节容易忽略，建议本地开发调试时优先使用 IDE 的运行时环境变量配置，而不是在启动参数里反复修改。

四、@Profile 控制 Bean 的条件装配

Profile 不仅能切换配置文件，还能控制 Spring 容器加载哪些 Bean。比如本地开发想要一个简单的内存缓存实现，生产环境需要接入 Redis。可以在两个实现类上标注不同 Profile，Spring 根据激活情况只创建对应的 Bean。

@Component
@Profile("dev")
public class InMemoryCache implements CacheService {
    private final Map<String, Object> store = new ConcurrentHashMap<>();
    @Override
    public Object get(String key) {
        return store.get(key);
    }
}
@Component
@Profile("prod")
public class RedisCache implements CacheService {
    private final RedisTemplate<String, Object> redisTemplate;
    public RedisCache(RedisTemplate<String, Object> redisTemplate) {
        this.redisTemplate = redisTemplate;
    }
    @Override
    public Object get(String key) {
        return redisTemplate.opsForValue().get(key);
    }
}

@Profile 也支持组合表达式，例如 @Profile("dev | test") 表示 dev 或 test 环境都创建该 Bean，@Profile("!prod") 表示非生产环境创建。注意竖线和感叹号在不同的版本中写法略有差异，Spring 5.3 之后还支持 & 表示同时满足。建议表达式尽量简单，复杂的组合逻辑放到配置属性判断中，否则可读性会很差。

在使用 @Profile 时还要注意与 @Configuration 类的配合。如果整个配置类标注了 @Profile，那么类中所有 @Bean 方法都只在对应 Profile 下生效。如果只想控制单个 Bean，可以在 @Bean 方法上标注。对于自动装配场景，如果一个 Bean 依赖另一个只在 prod 存在的 Bean，而当前激活的是 dev，会导致启动失败，此时可以用 @Autowired(required = false) 或提供默认 Bean 解决。

五、多环境切换的避坑建议

第一个常见问题是误连生产库。原因往往是生产配置里写了默认激活 prod，但开发同事在本地运行未覆盖，直接加载了生产配置。更安全的方式是主配置不设置 active，或者设置一个明确的本地默认值，同时在生产部署平台强制注入 SPRING_PROFILES_ACTIVE=prod。不要把生产账号密码放在公共 git 仓库，使用环境变量或配置中心覆盖。

第二个问题是多个 active profiles 可能同时生效。比如激活 prod 和 dev，Spring Boot 会同时加载 application-prod.yml 和 application-dev.yml，同名属性按文件加载顺序覆盖，结果可能不是预期。可以使用 spring.profiles.active=prod,common 这种刻意组合，但要清楚覆盖规则。也可以用 spring.profiles.group 定义一组 Profile，把相关环境打包激活。

spring:
  profiles:
    active: prod
    group:
      prod: prod,db-prod,redis-prod
      dev: dev,db-dev,redis-dev

第三个问题是测试环境与业务 Profile 混淆。测试类中可以用 @ActiveProfiles 指定 Spring 测试上下文使用的 Profile，避免依赖本机环境变量。测试代码里的 @ActiveProfiles 优先级高于应用默认配置，例如 @SpringBootTest 配合 @ActiveProfiles("dev") 可以让测试稳定在开发环境跑，而不受部署机器环境变量影响。这个习惯能显著减少 CI 流水线中的配置漂移。

总体来看，Spring Boot Profile 的关键在于理解它只是属性源和 Bean 注册的过滤条件，核心还是属性覆盖顺序。围绕这个机制建立团队规范，统一用 application-{profile}.yml 拆分差异配置，生产环境通过环境变量强制注入激活值，配合 @Profile 控制 Bean 装配，基本可以覆盖大多数多环境管理需求。