做 Java 后端的人应该都有过这种经历：代码在本地跑得好好的，一到测试环境就各种连不上数据库，端口被占，日志级别不对，第三方服务地址还是本地的 localhost。运气好改几个配置就能跑起来，运气不好还得在服务器上翻半天配置文件。Spring Boot 项目里要解决这种"换个环境就换一套配置"的痛点，靠的就是多环境配置文件机制。简单说，就是把不同环境下的差异配置拆成独立的文件，通过一个开关来切换，而不是每次上线前手工改配置。
这篇文章我把多环境配置这个话题从头到尾讲透，包含文件怎么拆、环境怎么切、部署时怎么传参、以及我实际踩过的一些坑。无论你是刚开始学 Spring Boot，还是做毕业设计、公司项目，这套方法都能直接抄作业。
1. 多环境配置到底要解决什么问题
1.1 为什么不能在代码里写死配置
很多刚接触 Spring Boot 的同学习惯把数据库地址、Redis 地址、文件存储路径这些东西直接写在application.yml里，本地跑通了就算完事。但这种写法在项目稍微正规一点之后，就会出大问题。
举个例子：你本地开发用的 MySQL 地址是localhost:3306，用户名是root，密码是123456。而生产环境是一台内网服务器10.0.0.15:3306，账号密码完全不同，而且数据库名也不一样。如果你每次发版都要手动改这些配置，第一个风险是"改漏了"——经常是数据库地址改了，日志级别忘改；Redis 密码改了，文件存储路径忘改。第二个风险是"改错了"——生产环境配置文件被误改成测试环境的地址，几分钟内就能把线上数据搞出问题。
多环境配置的核心思路是：把配置按环境拆开，用一套开关来切换。Switch 拨到dev，加载开发配置；拨到prod，加载生产配置。代码本身不需要改，打包产物也不需要重新生成，只是启动时多传一个参数的事。这样一来，环境差异就不会被"人肉记忆"和"手工修改"引入到生产环境里。
另外还有一个隐藏好处：多个开发人员在同一套代码上并行开发时，每个人本地有自己的配置文件，大家都用dev环境切自己的本地服务，互不干扰。如果有人把配置提交到 Git 里，也不会有合并冲突，因为公共配置和私有配置是分开的。
1.2 Spring Boot 配置加载机制速览
在讲怎么写多环境配置之前，先简单看一眼 Spring Boot 是怎么加载配置的。
Spring Boot 启动时会创建一个Environment对象，这个对象里维护了一个属性源列表（PropertySourceList）。它按照固定优先级合并各种来源的配置，比如：命令行参数优先级最高，然后是 Java 系统属性、环境变量、application-{profile}.yml、application.yml，最后是各种扩展配置。
这里有一个关键逻辑：后加载的配置覆盖先加载的配置。举个例子，你在application.yml里写了server.port: 8080，在application-prod.yml里写了server.port: 8081，那么当spring.profiles.active=prod时，实际生效的端口就是 8081。Spring Boot 的 Profile 机制本质上就是"在标准配置之上叠加一层环境专用配置"，而不是把整个配置文件重写一遍。
理解了这层逻辑，你就明白为什么多环境配置不会导致"配置丢失"——公共配置写在application.yml里，环境差异写在application-{环境名}.yml里，两者是合并关系，而不是互斥关系。
2. 标准拆分写法与五种环境指定方式
2.1 目录结构与命名规则
Spring Boot 多环境配置的标准做法很简单。你的src/main/resources目录下，除了一个application.yml（或者application.properties），再放几个命名规则为application-{环境名}.yml的文件。
比如一个常见的电商项目结构如下：
src/main/resources/ ├── application.yml ├── application-dev.yml ├── application-test.yml └── application-prod.ymlapplication.yml：存放公共配置，比如应用名、编码、通用依赖信息。application-dev.yml：开发环境配置，一般是本地连接地址、调试日志级别。application-test.yml：测试环境配置，通常是测试服务器地址、相对完整的日志。application-prod.yml：生产环境配置，严格日志、连接池参数、告警相关配置。
命名规则不要乱起，比如application-dev.yml、application-development.yml这种别名尽量少用，统一风格便于维护。Spring Boot 2.4 之后支持多文档块（spring.config.activate.on-profile），这种方式也可以实现类似效果，但坦白说，多文件拆分的方式更直观，排查问题时打开哪个文件一目了然，我个人还是推荐文件拆分。
2.2 五种指定环境的方式对比
写好文件之后，怎么告诉 Spring Boot 当前激活哪个环境？这里有五种常见方式，我整理成一张表。
| 方式 | 示例 | 优先级（高到低） |
|---|---|---|
| 命令行参数 | java -jar app.jar --spring.profiles.active=prod | 最高 |
| 系统环境变量 | export SPRING_PROFILES_ACTIVE=prod | 较高 |
| JVM 系统参数 | java -Dspring.profiles.active=prod -jar app.jar | 中 |
| 配置文件中指定 | application.yml里spring.profiles.active: prod | 低 |
| 容器编排环境变量 | Docker Compose / K8s 中设置SPRING_PROFILES_ACTIVE | 较高 |
这里有个细节值得注意：Spring Boot 官方更推荐SPRING_PROFILES_ACTIVE环境变量写法，因为"环境变量"这种机制在部署平台里天然存在，无论是 Linux 服务器、Docker 还是 Kubernetes 都统一支持。如果你在application.yml里写死了spring.profiles.active: dev，那万一你忘了在部署时覆盖，生产环境就照着 dev 配置启动了，这是个很低级但很容易犯的错。
我个人的经验是：**application.yml里不写死spring.profiles.active，而是用占位符spring.profiles.active: ${SPRING_PROFILES_ACTIVE:dev}**，这样本地启动默认走 dev，部署时通过环境变量覆盖；即便覆盖失败，也不会把生产环境搞成测试环境。
另外，IDEA 还是 VS Code 这类 IDE 里也可以在 Run Configuration 的环境变量中配置，这样本地调试不同环境时不用改代码，非常方便。
3. 一份完整的多环境配置实例拆解
3.1 数据源、日志和第三方服务怎么拆
知道了拆分规则，下面拿一个实际项目做例子，我们把一个常见的商城后端拆成 dev / prod 两套配置，看看到底哪些放公共，哪些放环境差异。
先是公共的application.yml：
spring: application: name: mall-service profiles: active: ${SPRING_PROFILES_ACTIVE:dev} jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8 server: servlet: context-path: /api mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl再是application-dev.yml：
server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/mall_dev?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: 123456 redis: host: localhost port: 6379 logging: level: com.example.mall: debug然后是application-prod.yml：
server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://10.0.0.15:3306/mall_prod?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: mall_prod password: ${MYSQL_PASSWORD} redis: host: 10.0.0.16 port: 6379 password: ${REDIS_PASSWORD} logging: level: com.example.mall: info注意几个细节。
第一，application.yml中的mybatis-plus.configuration.log-impl是公共配置，但 dev 和 prod 其实有差异——prod 环境显示 SQL 日志会拖累性能，且容易泄露数据细节。所以更合理的做法是把这个 SQL 日志配置放到application-dev.yml里，prod 环境不打印 SQL，这是很多人容易忽略的点。
第二，prod 环境里的密码不要写明文。这里用${MYSQL_PASSWORD}这种占位符，从系统环境变量中取值。部署时在服务器或者容器平台里配置好环境变量，项目里根本看不到真实密码。这个习惯非常值得养成，一旦配置仓库泄露，不至于把数据库密码也一起交代了。
第三，连接池参数这种"环境差异明显"的配置，可以单独拆到每个环境的配置文件里。比如 dev 环境连接池初始大小 5，prod 环境初始大小 20，最大连接数差异很大，如果只写在公共配置里，切换环境反而会互相干扰。
3.2 随机端口与 Banner 的小技巧
多环境配置里还有一些好用的小技巧，可以让你的日常开发更舒服。
首先是随机端口。你在本地开发时，如果一个 Spring Boot 项目开了多个实例，或者8080端口被其他应用占用，每次都要手动改端口会很烦。可以用${random.int(10000,19999)}这个随机数占位符来实现。在application-dev.yml里写：
server: port: ${random.int(10000,19999)}每次启动本地实例时端口都是随机生成的，多个实例同时启动也不会冲突。注意这个写法只适合 dev 这种非对外暴露端口的环境，生产环境端口还是要固定下来，否则反向代理和防火墙配置就不好弄了。
其次是 Banner 关闭。Spring Boot 启动时默认会打印一个大大的 ASCII Art 图标，本地看着还行，但日志采集系统里这串东西很占地方。如果想让某个环境的启动日志干净一些，可以在环境配置里设置：
spring: main: banner-mode: "off"日志级别同理。上线之后还在打 debug 级别的日志，流量一大磁盘就会暴涨，这个问题非常多见。把logging.level的细节分开写，比在公共配置里统一设置要科学得多。
4. 部署时如何正确切换环境
4.1 打包与启动参数传递
写完多环境配置文件，接下来这一步才是真正决定"配置能否正确生效"的关键：部署时的参数传递。
第一种是 jar 包方式。执行java -jar mall-service.jar --spring.profiles.active=prod，这个命令会把命令行参数作为最高优先级传给 Spring Boot。命令行参数是最直观的方式，缺点是你得保证启动脚本里写了这个参数，如果写脚本的人忘了，那环境就切不过去了。
第二种是环境变量方式。在 Linux 服务器上，用如下方式启动：
export SPRING_PROFILES_ACTIVE=prod export MYSQL_PASSWORD='StrongPassw0rd' java -jar mall-service.jar在 systemd 服务文件或者 supervisor 配置文件里，也可以设置Environment=SPRING_PROFILES_ACTIVE=prod，效果一样。
再说一个和 Maven 相关的细节。很多项目会把 Maven 的 profile 和 Spring Boot 的 profile 搞混，这两个名字一样但完全是两码事。Maven 的 profile 控制的是"打包时的行为"，比如要不要打入测试依赖、要不要进行资源过滤；Spring Boot 的 profile 控制的是"运行时的配置加载"。不要试图用 Maven profile 来替换 Spring Boot profile。
如果你确实需要"一套代码构建出不同配置的包"，可以在 Maven 的 pom.xml 里结合 resource filtering 来做，但这种方式在现在用得非常少，因为它会破坏"一个包到处跑"的便利性。现在主流做法还是：打一个通用的 jar 包，运行时通过SPRING_PROFILES_ACTIVE指定环境。这也是容器化部署时代更推崇的方式——镜像只构建一次，任意环境都能跑。
4.2 Docker 部署时的环境注入
Docker 部署 Spring Boot 项目时，环境变量的优先级和裸机启动是一样的。一个典型的 Dockerfile 大概是这样的：
FROM openjdk:17-jdk-slim WORKDIR /app COPY target/mall-service.jar app.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "app.jar"]启动容器时把环境变量传进去：
docker run -d \ --name mall-prod \ -p 8080:8080 \ -e SPRING_PROFILES_ACTIVE=prod \ -e MYSQL_PASSWORD='StrongPassw0rd' \ -e REDIS_PASSWORD='RedisPassw0rd' \ mall-service:1.0.0关键是-e那一串。SPRING_PROFILES_ACTIVE=prod会告诉 Spring Boot 加载application-prod.yml，而${MYSQL_PASSWORD}占位符则从容器环境变量里取值。
用 Docker Compose 时写法类似：
version: "3.8" services: mall-service: image: mall-service:1.0.0 ports: - "8080:8080" environment: - SPRING_PROFILES_ACTIVE=prod - MYSQL_PASSWORD=StrongPassw0rd - REDIS_PASSWORD=RedisPassw0rd这里要特别提醒：不要把MYSQL_PASSWORD=123456这种真实密码直接写进 docker-compose.yml 文件里，尤其是如果这个文件会上传到 Git 仓库。正确做法是在部署服务器上准备一个.env文件，把敏感变量放在里面，.env文件不进 Git；或者直接用 Kubernetes 的 Secret 管理。
实际上，线上问题最多的不是"环境变量没传"，而是"传了但名字拼错了"——比如你写SPRING_PROFILE_ACTIVE（少了最后的 S），Spring Boot 完全感知不到，默认走了 dev。我排查过好几次这个问题，最后都是随手敲键盘漏了一个字母导致的。这也是为什么我建议在application.yml里把默认值设成dev，这样，拼错时不会直接打到生产库，好歹是个防护。
5. 常见问题与排查实录
5.1 遇到过的那些坑
配置解析和加载的问题，一个项目多了之后什么样的情况都会遇到。这里把几个常见的坑列出来，给后来人排雷。
问题一：为什么我改了application-prod.yml里的端口，启动后没生效？
排查顺序如下。先确认激活的确实是 prod 环境：看启动日志里The following 1 profile is active: "prod"；再看配置文件的优先级是否被覆盖，比如有没有在启动命令里额外加了--server.port=9090，命令行参数优先级高于文件配置；最后看有没有多个application.yml，比如resources目录下和target/classes目录下各有一个旧版本的配置文件，清理后重新打包再启动。
问题二：环境变量传了SPRING_PROFILES_ACTIVE=prod，但还是加载 dev 配置？
先检查变量名是否写对，是SPRING_PROFILES_ACTIVE不是SPRING_PROFILE_ACTIVE。再检查这个环境变量是否真的传到了应用进程里，在启动脚本里加一行echo $SPRING_PROFILES_ACTIVE看看能否输出。如果用的是 systemd，注意EnvironmentFile路径是否正确；如果是 Docker，注意-e参数的位置是否放到了镜像名之后（docker run的参数顺序很重要）。还有一种可能是容器里既有环境变量也有命令行参数，后者的优先级高于前者，命令行参数把环境变量覆盖了。
问题三：application.yml里写的密码带特殊字符，启动时报 YAML 语法错误？
这是 YAML 解析的老大难问题。比如密码是abc@123#456，其中@在 YAML 未加引号的值里是允许的，但如果你用${PASSWORD}替换，环境变量里的值包含#或冒号（:），在 YAML 里就会被解析成注释或层级分隔符。解决办法是把这些占位符用引号包起来：
password: "${MYSQL_PASSWORD}"这样无论环境变量里的值含什么特殊字符，都会以字符串形式整体读入。
问题四：config 目录下多环境配置文件很多，IDEA 或 VS Code 里每个文件的 YAML 校验报错？
IDEA 默认会对application-*.yml做 profile 识别，但有时需要手动指定活跃的 profile 才能正确校验。在 IDEA 的 Run Configuration 里给Active profiles填上dev，再用 Spring 插件启动，编辑器就能按对应 profile 来识别配置属性了。如果 VS Code 的 Spring Boot 插件不生效，可以先看看插件是否识别出你这个项目是 Maven 还是 Gradle 构建的，识别失败就会影响配置提示。
5.2 进阶玩法：配置中心与周边工具
当项目规模变大，环境数量增多（比如有灰度环境、压测环境、多地域环境），纯靠application-{env}.yml文件管理配置会越来越吃力。配置文件分散在每个微服务项目里，改一个公共配置要全部重新发版，这时候就可以考虑引入配置中心，比如 Apollo、Nacos 或者 Spring Cloud Config。
配置中心的核心思路是：把"环境差异配置"从项目里抽出来，放到一个集中管理的配置服务上。项目启动时先拉取远程配置，和本地配置做合并，本地配置优先级低于远程配置。这样改配置不用重新打包，动态刷新生效，特别适合服务实例多的场景。
但如果你是单体项目或者刚起步的项目，我建议不要一上来就上配置中心，配置中心本身也有运维成本。先把多环境文件拆分这件事做扎实，等真正遇到"配置改不动、发版太频繁"的痛点，再去上配置中心也不迟。
周边工具里，还有一个值得提的是 SpringDoc 的开关。我们经常在开发环境开着 Swagger UI 文档方便调试，但生产环境如果默认开着接口文档，等于把接口结构公开了，存在信息泄露风险。可以参考这种方式，把 SpringDoc 的开关放到环境配置里：
# application-prod.yml springdoc: api-docs: enabled: false swagger-ui: enabled: falsedev 环境保持开启，prod 环境强制关闭，一套配置各管各的，非常干净。类似的还有management.endpoints.web.exposure.include这种 Actuator 的端点暴露配置，开发环境可以放宽一点，生产环境只暴露health即可。这些都是多环境配置的延伸应用场景。
5.3 配置排查速查表
把前面遇到的问题整理成一张速查表，方便你对照排查。
| 症状 | 可能原因 | 排查方法 |
|---|---|---|
| profile 没生效 | 环境变量名拼写错误 | 检查SPRING_PROFILES_ACTIVE是否多字少字 |
| 配置被覆盖 | 命令行参数优先级更高 | 检查启动命令里的--key=value参数 |
| 端口起不来 | 随机端口和固定端口混用 | 确认application-{env}.yml里server.port是唯一的 |
| 数据库密码解析错 | 特殊字符未加引号 | 占位符用"${...}"包裹 |
| 打包后配置还是旧的 | target目录有残留 | 执行mvn clean package |
| 多环境文件互相干扰 | 公共配置里写了环境差异项 | 把环境差异配置从application.yml移到对应环境文件 |
6. 我的实践心得：多环境配置的正确"打开方式"
最后分享几点个人经验。
第一，不要把环境配置复杂化。有些新手喜欢在application.yml里写一大堆spring.config.import、spring.profiles.group之类的进阶特性，结果环境一多自己都绕晕了。多环境配置的第一原则是"简单直观、一眼能看懂"。团队协作时，别人打开你的配置目录，能快速知道哪个文件负责哪个环境，比炫技重要得多。
第二，本地开发的application-dev.yml尽量保留一些"个人化"配置空间。你可以把 dev 配置提成公用的，但每个人本地的端口、本地数据库地址可能不一样。常见的做法是一个人维护一份application-local.yml，这个文件不进 Git，专门放自己的私有配置，然后用spring.profiles.active=local启动。
第三，配置文件的注释一定要写清楚。这个值为什么这么配？哪个系统的地址？账号权限到哪一级？这些背景信息如果不写，三个月后你自己回来看都猜不到当初为什么这么设。尤其像连接池参数、超时时间这种"调参型"配置，把当时的考虑写进注释，就是给未来的自己省时间。
第四，环境配置的变更记录能沉淀尽量沉淀。生产环境的配置改动，哪怕只是换了一个数据库密码，也应该走一遍变更记录流程。我之前在排查线上问题时，经常发现"配置突然不生效"是因为有人直接在服务器上改了配置文件，但改了一半没改完。后来我要求所有配置改动都必须同步到项目仓库，服务器上不再允许手动编辑配置，这个问题才彻底消失。
多环境配置看起来只是文件拆分，往深了说，它其实是"交付物与环境解耦"这个理念的具体落地。一个 jar 包可以跑在任何环境，只是运行时带上不同的开关，这在传统运维时代是为了省事，在容器化和云原生时代则是必备能力。把这一层想明白，你写配置的时候自然就会往"外部化、可覆盖、可追溯"的方向走。
