Spring-Profile与部署说明

Spring Profile 与部署说明

本文档说明 Spring Boot 激活环境（profile） 的生效方式、优先级，以及 Docker Compose 部署 时环境变量的传递机制。

一、`spring.profiles.active` 的优先级（从高到低）

Spring Boot 确定「当前激活的 profile」时，按以下顺序取第一个有值的来源：

优先级	来源	说明
1（最高）	程序参数	运行配置中的 `--spring.profiles.active=xxx`，或 IDE 的 Active profiles（会转成程序参数）
2	JVM 参数	VM options 中的 `-Dspring.profiles.active=xxx`
3	环境变量	操作系统/进程环境变量 `SPRING_PROFILES_ACTIVE=xxx`（如 Docker Compose 的 `environment`）
4	配置文件	`application.properties` / `application.yml` 中的 `spring.profiles.active=xxx`
5（最低）	未设置	以上都未配置时，无激活 profile 或按框架约定视为 default

同一种来源内，先被读取到的生效；高优先级会覆盖低优先级。

二、指定激活环境的几种方式

方式	典型场景
1. IDE 运行配置	在 Run Configuration 的 Active profiles 填 `dev` / `test` / `prod`，或 Program arguments 填 `--spring.profiles.active=dev`
2. VM options	运行配置中 VM options 填 `-Dspring.profiles.active=dev`
3. 环境变量	系统或容器环境变量 `SPRING_PROFILES_ACTIVE=dev`（Docker Compose 即此类）
4. 配置文件	在 `application.properties` 或 `application.yml` 中写 `spring.profiles.active=dev`
5. Maven + 插件	使用 Maven 运行配置执行 `spring-boot:run`，由 POM 中 `<arguments>--spring.profiles.active=${application.environment}</arguments>` 传入，此时 Maven 勾选的 profile 会生效

三、IDE 直接运行 vs Maven 运行

直接点运行主类 （Spring Boot / Application 运行配置）：

不会执行 Maven，因此不会使用 Maven 的 profile 或 POM 里 spring-boot-maven-plugin 的 <arguments>。

激活环境由 运行配置里的 Active profiles / Program arguments 或上面优先级表中的 2～5 决定。
用 Maven 运行配置 （执行 spring-boot:run）：

会执行 Maven，会使用当前勾选的 Maven profile 和 POM 中的
<arguments>--spring.profiles.active=${application.environment}</arguments>，

即「勾选 Maven 的 profile → 点运行」即可切换 Spring 的激活环境。

四、Docker Compose 中 `SPRING_PROFILES_ACTIVE` 如何传递

4.1 在优先级中的位置

Docker Compose 的 environment 会变成容器内的环境变量 ，对应上表中的 优先级 3 。

若未在启动命令中传入程序参数或 JVM 参数，则会使用这里的 SPRING_PROFILES_ACTIVE。

示例：

yaml 复制代码

your-app:
  image: your-app:latest
  environment:
    SPRING_PROFILES_ACTIVE: test
    SPRING_CLOUD_NACOS_SERVER_ADDR: nacos:8848

4.2 传递链路

复制代码

docker-compose 的 environment
    ↓
容器进程的环境变量（如 export SPRING_PROFILES_ACTIVE=test）
    ↓
容器内启动的 Java 进程（如 java -jar app.jar）继承该环境
    ↓
Spring Boot 启动时按「宽松绑定」规则读取环境变量
    ↓
SPRING_PROFILES_ACTIVE → 映射为 spring.profiles.active → 激活对应 profile（如 test）

宽松绑定 ：环境变量大写+下划线（SPRING_PROFILES_ACTIVE）自动对应配置项小写+点号（spring.profiles.active），无需在代码中手写读取逻辑。

五、Docker Compose 部署需要哪些文件

文件	是否必须	作用
docker-compose 文件	必须	定义服务如何运行：镜像、端口、环境变量、依赖服务（如配置中心、数据库）等；执行 `docker compose up` 时使用。
Dockerfile	必须（若自建镜像）	定义如何将应用打成镜像（如 JDK、jar、启动命令）；`image: your-app:latest` 需通过 Dockerfile 构建或从仓库拉取。
Jenkinsfile	非必须	用于 Jenkins CI/CD 流水线（编译、构建镜像、推送、部署）；仅在使用 Jenkins 做自动化时需要，与「能否用 docker compose 启动」无直接关系。

结论：仅就「用 Docker Compose 启动应用」而言，需要 Dockerfile + docker-compose 文件；Jenkinsfile 仅在采用 Jenkins 做流水线时才需要。

六、常见配置文件约定

bootstrap.properties / application.properties：公共配置（如配置中心、注册中心地址等）。
bootstrap-{profile}.properties / application-{profile}.properties ：按 profile 区分的环境配置，例如：
- bootstrap-dev.properties（本地开发）
- bootstrap-test.properties（测试）
- bootstrap-prod.properties（生产）

激活的 profile 决定加载哪一个 *-{profile}.properties。