Spring Boot 3.x 多环境配置管理实战

多环境配置是每个 Java 后端项目都绕不开的话题。开发环境、测试环境、生产环境的数据库地址、日志级别、API 密钥等各不相同，如何优雅地管理它们而不出错？本文从实践出发，分享一套经过验证的方案。

一、按环境拆分 application.yml

Spring Boot 原生支持通过 application-{profile}.yml 的命名约定来拆分配置。基础配置放 application.yml，各环境差异放对应的 profile 文件。

src/main/resources/
├── application.yml          # 公共配置
├── application-dev.yml      # 本地开发
├── application-test.yml     # 测试环境
└── application-prod.yml     # 生产环境

application.yml（公共配置）：

spring:
  application:
    name: my-service
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: Asia/Shanghai

server:
  servlet:
    context-path: /api

myapp:
  version: @project.version@
  max-upload-size: 10MB

application-dev.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/myapp_dev
    username: root
    password: root
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

logging:
  level:
    com.myapp: DEBUG

application-prod.yml：

spring:
  datasource:
    url: jdbc:mysql://prod-db:3306/myapp
    username: ${DB_USER}
    password: ${DB_PASS}
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: validate

logging:
  level:
    com.myapp: WARN

二、Maven Profile 驱动

在 pom.xml 中定义 profile，与 Spring Boot 的 profile 联动，实现构建时自动切换。

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <spring.profiles.active>dev</spring.profiles.active>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <spring.profiles.active>prod</spring.profiles.active>
        </properties>
    </profile>
</profiles>

在 application.yml 中引用 Maven 属性：

spring:
  profiles:
    active: @spring.profiles.active@

三、Docker 容器化部署

构建时通过 Maven profile 打包，运行容器时指定 profile 和环境变量：

# 构建生产包
mvn clean package -Pprod

# Dockerfile
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

# docker-compose.yml
version: "3.8"
services:
  myapp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - DB_USER=${DB_USER}
      - DB_PASS=${DB_PASS}
    env_file:
      - .env.prod
    restart: always

四、常见问题与解决方案

1. 配置不生效

检查 @SpringBootTest 是否指定了 profile：@ActiveProfiles("test")。另外注意 application.yml 中的 spring.profiles.active 优先级低于命令行参数和环境变量。

2. 敏感信息泄漏

用 ${VAR} 占位符配合环境变量是最简单的方案。进阶可以使用 Spring Cloud Config、Vault 或 jasypt-spring-boot 加密。

3. 配置项过多

按功能拆分为多个配置类，使用 @ConfigurationProperties 绑定，并开启 spring-boot-configuration-processor 获得 IDE 提示。

@ConfigurationProperties(prefix = "myapp.oss")
@Data
public class OssProperties {
    private String endpoint;
    private String accessKey;
    private String secretKey;
    private String bucket;
}