springboot maven 多环境配置入门与实战

Spring Boot3 Maven 项目地址

https://gitee.com/supervol/loong-springboot-study

（记得给个start，感谢）

Maven 介绍

        在 Spring Boot 3 + Maven 项目中，多环境配置的核心目标是：在不同环境（如开发、测试、生产）下，无需手动修改配置文件，即可通过 Maven 命令或 IDE 快捷切换，加载对应环境的专属配置（如数据库连接、端口号、第三方 API 地址等），避免配置冲突和手动操作失误。

Maven 核心

        在配置前需明确两个易混淆的概念：

概念	作用范围	核心目的
Spring Boot Profile	应用运行时	决定应用启动时加载哪组application-{profile}.yaml配置文件
Maven Profile	Maven 构建过程（编译、打包）	决定构建时使用哪组 Maven 属性（如依赖版本、资源过滤规则）

        实际使用中，通常将两者联动：通过激活 Maven Profile，间接指定 Spring Boot Profile，实现 “构建 + 运行” 的环境统一。

Maven 前提

        Spring Boot 3 通过配置文件命名规范实现环境隔离，所有配置文件需放在src/main/resources目录下。

1. 配置文件结构

        需创建 1 个主配置文件（存放所有环境的公共配置）和 N 个环境专属配置文件（存放各环境的差异化配置），命名必须遵循 Spring Boot 约定：

src/main/resources/
├─ application.yaml          # 主配置文件（公共配置，如日志级别、上下文路径）
├─ application-dev.yaml      # 开发环境配置（本地数据库、调试端口）
├─ application-test.yaml     # 测试环境配置（测试数据库、测试API）
└─ application-prod.yaml     # 生产环境配置（生产数据库、安全端口、HTTPS）

2. 配置文件内容示例

（1）主配置文件：application.yaml

        存放所有环境的公共配置，同时可通过spring.profiles.active指定默认激活的环境（若未通过 Maven 指定，将使用此默认值）：

# 公共配置：所有环境共用
server:servlet:context-path: /api
logging:level:root: INFO# 默认激活的环境（若Maven未指定，将用dev）
spring:profiles:active: dev

（2）开发环境：application-dev.yaml

        仅存放开发环境的差异化配置（覆盖或补充主配置）：

# 开发环境：本地数据库、调试端口
server:port: 8080  # 开发端口用8080spring:datasource:url: jdbc:mysql://localhost:3306/dev_db?useSSL=false&serverTimezone=UTCusername: rootpassword: 123456  # 本地数据库密码

（3）生产环境：application-prod.yaml

        生产环境需考虑安全性和性能，配置更严格：

# 生产环境：安全端口、远程数据库
server:port: 443    # 生产用HTTPS默认端口443ssl:enabled: truekey-store: classpath:prod-ssl.jks  # 生产SSL证书spring:datasource:url: jdbc:mysql://prod-db.example.com:3306/prod_db?useSSL=true&serverTimezone=UTCusername: prod_userpassword: ${DB_PASSWORD}  # 生产密码优先从环境变量读取（避免硬编码）

Maven 配置

        在pom.xml中定义 Maven Profile，通过属性传递指定 Spring Boot 激活的环境，同时控制资源过滤（避免打包无用的配置文件）。

1. 定义 Maven Profile

        在pom.xml的profiles标签中，分别定义dev、test、prod三个 Profile，并设置spring.profiles.active属性：

<project><!-- 其他配置：groupId、artifactId、parent等 --><!-- 1. 定义Maven Profile --><profiles><!-- 开发环境Profile --><profile><id>dev</id>  <!-- Profile唯一标识，与Spring Boot Profile名一致 --><activation><activeByDefault>true</activeByDefault>  <!-- 默认激活dev（可选） --></activation><properties><!-- 传递属性给Spring Boot：激活dev环境 --><spring.profiles.active>dev</spring.profiles.active></properties></profile><!-- 测试环境Profile --><profile><id>test</id><properties><spring.profiles.active>test</spring.profiles.active></properties></profile><!-- 生产环境Profile --><profile><id>prod</id><properties><spring.profiles.active>prod</spring.profiles.active></properties></profile></profiles><!-- 2. 配置资源过滤（可选，优化打包） --><build><resources><resource><directory>src/main/resources</directory><filtering>true</filtering>  <!-- 开启资源过滤：替换配置文件中的Maven属性 --><includes><!-- 打包时仅包含主配置和当前激活环境的配置 --><include>application.yaml</include><include>application-${spring.profiles.active}.yaml</include><!-- 若有SSL证书等资源，需手动包含 --><include>*.jks</include></includes></resource></resources><!-- 3. 配置Spring Boot Maven插件（传递Profile属性） --><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>3.2.0</version>  <!-- 与Spring Boot版本一致 --><configuration><!-- 运行时传递Maven属性给Spring Boot --><arguments><argument>--spring.profiles.active=${spring.profiles.active}</argument></arguments></configuration></plugin></plugins></build>
</project>

2. 关键说明：

• 资源过滤（filtering: true）：开启后，配置文件中@属性名@格式的占位符会被 Maven 属性替换（如@spring.profiles.active@）。
• includes 标签：控制打包时仅包含主配置和当前激活环境的配置，避免将application-dev.yaml打包到生产环境的 JAR 中，减少安全风险。

Maven 激活

        配置完成后，可通过命令行或IDE激活不同环境，无需修改代码。

1. 命令行激活

        在项目根目录执行 Maven 命令，通过-P指定激活的 Maven Profile（间接激活 Spring Boot Profile）。

（1）运行开发环境

# 激活dev Profile，启动开发环境（端口8080，本地数据库）
mvn spring-boot:run -Pdev

（2）打包生产环境 JAR

# 激活prod Profile，打包生产环境JAR（仅包含application.yaml和application-prod.yaml）
mvn clean package -Pprod

（3）运行生产环境 JAR

        打包后，直接运行 JAR（Spring Boot 会自动加载prod环境配置）：

# 生产环境运行（若密码存环境变量，需先设置）
export DB_PASSWORD=prod_secure_password
java -jar target/your-project-name-0.0.1-SNAPSHOT.jar

2. IDE 激活

        以 IntelliJ IDEA 为例，无需命令行，通过界面选择激活的 Profile：

1. 打开右侧「Maven」面板 → 展开「Profiles」；
2. 取消默认的dev勾选，勾选需要激活的 Profile（如test）；
3. 点击「运行」按钮（▶️），IDE 会自动使用勾选的 Profile 启动项目。

Maven 示例

        请参考项目地址中 springboot-env/springboot-env-maven 模块代码。

Maven 进阶

        当同一配置项在多个地方定义时，Spring Boot 3 遵循以下优先级顺序（高优先级覆盖低优先级）：

1. 命令行参数（如java -jar app.jar --server.port=8888）；
2. 环境变量（如export SPRING_DATASOURCE_PASSWORD=xxx）；
3. 环境专属配置文件（application-prod.yaml）；
4. 主配置文件（application.yaml）；
5. 默认属性（Spring Boot 内置默认值）。

        建议：生产环境的敏感信息（如数据库密码、API 密钥）优先通过「环境变量」或「配置中心」（如 Nacos、Apollo）传递，避免硬编码到配置文件中。

Maven 注意

1. 配置文件未加载？

   • 检查文件名是否符合规范：必须是application-{profile}.yaml（大小写敏感，如application-DEV.yaml无效）；
   • 检查 Maven Profile 是否正确激活：执行mvn help:active-profiles查看当前激活的 Profile。

2. Maven 属性未替换？

   • 确保pom.xml中resource标签的filtering已设为true；
   • 配置文件中的占位符格式是否正确：使用@属性名@（而非${属性名}，${}是 Spring Boot 的占位符）。

3. 生产环境包含开发配置？

   • 检查pom.xml的includes标签，确保仅包含当前激活环境的配置文件（如application-${spring.profiles.active}.yaml）。

总结

        Spring Boot 3 + Maven 多环境配置的核心是 **“约定大于配置”**：

1. 遵循 Spring Boot 配置文件命名规范，隔离公共与环境专属配置；
2. 通过 Maven Profile 联动 Spring Boot Profile，实现构建与运行环境统一；
3. 利用命令行或 IDE 快速切换环境，敏感信息通过环境变量传递，保障安全。

        这种方案适用于中小型项目，若项目规模较大（如微服务），建议结合配置中心实现更灵活的多环境配置管理。