SpringBoot 各版本 Profile 多环境配置完整对比（2.x/ 2.4+ / 3.x/4.x

前言

在项目开发中，我们经常需要区分开发、测试、生产多套环境配置。SpringBoot 不同大版本对于 profile 多环境配置语法发生过破坏性变更，很多同学网上复制旧代码放到 SpringBoot3/4 项目出现警告、配置不生效问题。本文整理 SpringBoot2 早期、2.4 版本重大变更、SpringBoot3、SpringBoot4 全部写法，区分多文件拆分 和**单文件多文档块---**两种模式，同时标注废弃语法、踩坑点。

版本分界重点：

SpringBoot 2.0 ~ 2.3.x：旧语法

SpringBoot 2.4.0 及以上（包含 2.7.x、3.x、4.x）：新语法，废弃 spring.profiles，使用 spring.config.activate.on‑profile

一、两种实现方式介绍

方式 1：拆分多个配置文件（企业项目通用，全版本兼容） resources 目录下放置多个独立配置文件，命名规则：application-{profile名}.yml/yaml

application.yml：主公共配置文件，存放通用配置，指定激活哪一个环境
application-dev.yml：开发环境
application-test.yml：测试环境
application-prod.yml：生产环境

加载规则：一定会加载主文件application.yml，再加载被spring.profiles.active激活的环境配置文件；相同 key，环境配置覆盖主配置。该写法所有 SpringBoot 版本全部兼容，无版本差异。

方式 2：单文件多文档块 --- 全部配置写在同一个application.yml，使用---分割多个配置块。

⚠️ 该语法只有 yml/yaml 格式支持，properties 文件不支持多文档块。这里语法随版本发生重大改动，是踩坑重灾区。

二、SpringBoot 2.0 ~ 2.3.x（旧版本）

适用：SpringBoot2.0、2.1、2.2、2.3

1）拆分多文件写法（全版本通用）

application.yml

复制代码

spring:
  profiles:
    active: dev # 激活dev环境
server:
  servlet:
    context-path: /

application-dev.yml

复制代码

server:
  port: 8081
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/test_db
    username: root
    password: 123456

2）单文件多文档块（旧语法，2.3 及以前可用）

复制代码

# 公共配置
spring:
  profiles:
    active: dev
server:
  servlet:
    context-path: /

# dev环境
---
spring:
  profiles: dev  #旧语法，2.3及之前有效
server:
  port: 8081
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/test_db
    username: root
    password: 123456

# prod环境
---
spring:
  profiles: prod
server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://线上ip:3306/prod_db
    username: root
    password: 654321

旧版本关键字：spring.profiles: dev

三、SpringBoot2.4.x ~ 2.7.x（重大语法变更）

2.4 开始废弃 spring.profiles: dev，继续使用旧语法控制台输出警告，配置可能出现加载异常。注意：拆分多文件写法完全不变，只有单文件多文档块语法改变。

1）拆分多文件写法【不变，推荐】

和 2.0‑2.3 完全一样，不受版本升级影响，企业项目优先选择。

2）单文件多文档块 ✅新正确写法

复制代码

# ==========公共配置块，必须写在最前面==========
spring:
  application:
    name: demo-app
  profiles:
    active: dev # 激活环境，只能写在公共块
server:
  servlet:
    context-path: /

# dev开发环境
---
spring:
  config:
    activate:
      on-profile: dev # ✅新关键字
server:
  port: 8081
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/test_db
    username: root
    password: 123456

# prod生产环境
---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://线上ip:3306/prod_db
    username: root
    password: 654321

❌禁止再写：spring.profiles: dev，该属性已经废弃。

四、SpringBoot3.x/ SpringBoot4.x（现在新项目）

SpringBoot3、4 完全继承 2.4 之后的规则，没有新改动。

拆分多文件写法：完全不变，兼容所有版本，最稳妥

单文件多文档块：必须使用spring.config.activate.on‑profile，旧语法直接废弃，警告。

完整 SpringBoot3 示例（单文件全部写在 application.yaml）

复制代码

# =====================公共配置=====================
spring:
  application:
    name: springboot‑demo
  profiles:
    active: dev
server:
  servlet:
    context-path: /

# dev环境
---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 8081
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/dev_db?useUnicode=true&characterEncoding=utf‑8&serverTimezone=Asia/Shanghai
    username: root
    password: 123456

# prod环境
---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 8080
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://线上ip:3306/prod_db?useUnicode=true&characterEncoding=utf‑8&serverTimezone=Asia/Shanghai
    username: root
    password: 654321

五、激活 Profile 的 4 种通用方式（全版本通用）

配置文件内激活（本地开发）

spring:
profiles:
active: dev

同时激活多个环境用逗号分隔

复制代码

spring:
  profiles:
    active: dev,redis

Jar 包命令行参数（线上部署优先级最高）

java -jar demo.jar --spring.profiles.active=prod
JVM 虚拟机参数（写在‑jar 前面）

java -Dspring.profiles.active=prod -jar demo.jar
Junit 测试类指定环境

@SpringBootTest
@ActiveProfiles("dev")
class DemoApplicationTest {
}

六、常见踩坑总结

properties 不支持---多文档块语法，只能拆分多个 properties 文件。
spring.profiles.active 只能写在公共配置块，不能写在被on‑profile修饰的文档块里面，否则不生效。
文件名必须英文横杠：application‑dev.yaml，中文横杠识别失败。后缀统一，不要 yml 和 yaml 混用。
SpringBoot2.4 + 不要继续复制网上老代码写spring.profiles: dev，会警告，部分场景配置加载异常。
优先级：JVM 参数 > jar 命令行参数 > yml 配置文件内spring.profiles.active。
加载规则：公共配置 + 激活的 profile 配置；相同 key，profile 配置覆盖公共配置。

七、选型建议

正式企业项目：优先拆分多个配置文件application‑dev.yaml，所有版本完全兼容，结构清晰，多人协作友好。
小型 demo、学习项目：可以使用单文件---多文档块，减少文件数量 ，SpringBoot3/4 务必使用spring.config.activate.on‑profile。