SpringBoot系列02：yml与properties配置全解，多环境profiles动态切换实战

hdsoft_huge2026-07-02 0:01

SpringBoot系列02：yml与properties配置全解，多环境profiles动态切换实战

📌 专栏系列：SpringBoot零基础进阶实战系列

🎯 文章难度：入门进阶（零基础可学，企业级实战）

💡 核心目标：彻底搞懂SpringBoot两大配置文件区别、加载优先级、多环境Profile动态切换，解决开发/测试/生产环境配置切换痛点，掌握企业级配置最佳实践

🔍 适用场景：日常开发环境配置隔离、项目上线环境切换、多环境配置统一管理、配置优先级冲突排查

一、前言：为什么SpringBoot需要配置文件？

在传统SSM项目中，我们需要编写大量XML配置文件，配置繁琐、冗余且可读性差。SpringBoot核心特性之一就是自动化配置 ，极大减少了手动配置，同时提供了两套极简的配置方案：application.properties 和 application.yml。

所有项目常量、环境参数、数据库连接、服务器参数、第三方接口配置，全部可以通过配置文件统一管理，无需修改代码、无需重启项目（部分配置）即可实现参数修改。

而在企业开发中，开发、测试、生产三套环境配置隔离是刚需，本文将从零讲解两种配置文件语法、核心区别、加载优先级，手把手实现多环境Profile动态切换，彻底解决环境配置混乱问题。

二、SpringBoot两大配置文件详解

SpringBoot项目默认支持两种配置格式，功能完全等价，均可实现项目所有配置，仅语法、可读性、层级表现力有区别。

2.1 properties配置文件（传统键值对）

application.properties 是SpringBoot默认的配置文件，也是传统Java项目常用的配置格式，语法简单、兼容性极强。

2.1.1 基础语法规则

  • 语法格式：key=value 键值对形式，一行一个配置

  • 注释格式：以 # 开头

  • 层级表达：通过 . 点分隔实现层级嵌套

  • 编码默认：ISO-8859-1（中文会乱码，需要手动设置）

2.1.2 实战配置示例
properties 复制代码 
# 服务器基础配置
server.port=8080
server.servlet.context-path=/

# 项目名称、日志级别
spring.application.name=springboot-config-demo
logging.level.com.example=DEBUG

# 数据库配置（多层嵌套）
spring.datasource.url=jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

2.2 yml配置文件（主流极简格式）

application.yml（YAML语言）是目前企业开发首选配置格式，以缩进式层级结构为主，语法简洁、可读性极高，完美适配SpringBoot分层配置思想。

2.2.1 基础语法规则

  • 语法格式：key: 空格 value，冒号后必须加空格

  • 层级规则：严格缩进（统一2个空格，禁止使用Tab）

  • 注释格式：以 # 开头

  • 编码默认：UTF-8（天然支持中文，无乱码问题）

  • 原生支持：对象、数组、集合、Map等复杂数据结构

2.2.2 实战配置示例
yaml 复制代码 
# 服务器配置
server:
  port: 8080
  servlet:
    context-path: /

# 项目配置
spring:
  application:
    name: springboot-config-demo
  # 数据库配置（层级清晰，直观易懂）
  datasource:
    url: jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

# 日志配置
logging:
  level:
    com.example: DEBUG

2.3 两种配置文件核心区别（重点）

很多开发者只会用，但不知道两种配置的优劣，下表总结企业级选型核心差异：

对比维度 properties yml
语法结构 扁平键值对，通过点分隔层级 缩进层级结构，天然分层
可读性 多层配置冗余、冗长 层级清晰，一目了然
数据结构支持 仅支持简单键值对，数组/对象表达繁琐 原生支持数组、对象、Map、集合
中文编码 默认ISO-8859-1，易乱码 默认UTF-8，完美支持中文
特殊功能 无 支持单文件多文档块、锚点复用配置
企业选型 简单小型项目、老旧项目兼容 中大型项目、微服务项目（首选）

三、配置文件加载优先级（高频面试+实战坑点）

SpringBoot启动时会自动加载多个路径的配置文件，优先级从高到低依次覆盖，高优先级配置会覆盖低优先级同名配置，这是90%配置失效、配置冲突的根源。

3.1 配置文件加载路径（优先级递减）

  1. 项目根目录/config目录（最高优先级）

  2. 项目根目录

  3. resources/config目录

  4. resources目录（默认配置存放位置，最低优先级）

3.2 同目录下格式优先级

同一目录下同时存在 application.properties 和 application.yml 时：

properties 优先级高于 yml，同名配置会覆盖yml配置！

避坑提醒 ：开发中建议只保留一种配置格式，避免多格式配置冲突，推荐统一使用yml。

四、自定义配置绑定（yml/properties通用）

除了SpringBoot内置配置，我们日常开发需要自定义业务配置，通过@ConfigurationProperties实现配置与实体类绑定，实现配置解耦。

4.1 yml自定义配置

yaml 复制代码 
# 自定义业务配置
custom:
  project: springboot-demo
  version: 2.0.0
  author: 技术博主
  # 数组配置
  server-list:
    - 127.0.0.1
    - 192.168.1.1

4.2 配置绑定实体类

java 复制代码 
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.List;

// 绑定自定义配置前缀
@ConfigurationProperties(prefix = "custom")
@Component
@Data
public class CustomConfig {
    private String project;
    private String version;
    private String author;
    private List<String> serverList;
}

4.3 测试获取配置

java 复制代码 
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;

@RestController
public class ConfigController {

    @Resource
    private CustomConfig customConfig;

    @GetMapping("/getConfig")
    public CustomConfig getConfig(){
        return customConfig;
    }
}

启动项目访问接口，即可成功读取yml自定义配置，properties配置绑定方式完全一致。

五、核心实战：多环境Profiles动态切换

企业开发标准环境划分：dev开发环境、test测试环境、prod生产环境，不同环境的端口、数据库、日志、接口地址完全不同，手动修改配置极易出错，SpringBoot Profile完美解决该问题。

5.1 环境配置文件命名规范

固定命名格式：application-{环境标识}.yml

  • 公共配置：application.yml（所有环境通用配置）

  • 开发环境：application-dev.yml

  • 测试环境：application-test.yml

  • 生产环境：application-prod.yml

加载规则：公共配置 + 当前激活环境配置，环境配置会覆盖公共配置同名参数

5.2 分步搭建多环境配置

第一步：编写公共配置（application.yml）
yaml 复制代码 
# 全局公共配置（所有环境生效）
spring:
  application:
    name: springboot-profile-demo
# 默认激活开发环境
  profiles:
    active: dev
第二步：编写开发环境配置（application-dev.yml）
yaml 复制代码 
# 开发环境：开启日志、本地数据库、自定义端口
server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/dev_db?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
logging:
  level:
    root: INFO
    com.example: DEBUG
第三步：编写测试环境配置（application-test.yml）
yaml 复制代码 
# 测试环境：测试服务器数据库、端口8081
server:
  port: 8081
spring:
  datasource:
    url: jdbc:mysql://192.168.1.100:3306/test_db?useSSL=false&serverTimezone=Asia/Shanghai
    username: test
    password: test123
第四步：编写生产环境配置（application-prod.yml）
yaml 复制代码 
# 生产环境：关闭调试日志、生产数据库、端口80
server:
  port: 80
spring:
  datasource:
    url: jdbc:mysql://192.168.1.200:3306/prod_db?useSSL=false&serverTimezone=Asia/Shanghai
    username: prod
    password: Prod@123456
logging:
  level:
    root: WARN
    com.example: WARN

5.3 四种动态切换环境方式（全覆盖）

方式1：配置文件激活（开发常用）

在公共配置 application.yml 中修改激活环境：

yaml 复制代码 
spring:
  profiles:
    active: test # 切换为 test / prod / dev
方式2：IDE启动参数激活（本地调试常用）

IDEA 点击 Run -> Edit Configurations -> VM Options 输入：

Plain 复制代码 
-Dspring.profiles.active=prod

优先级高于配置文件，临时切换环境首选。

方式3：命令行参数激活（服务器部署必备）

项目打包为jar包后，服务器启动时动态指定环境，无需修改代码和配置：

Plain 复制代码 
# 激活生产环境启动项目
java -jar springboot-demo.jar --spring.profiles.active=prod

企业生产首选，运维部署无需改动项目源码。

方式4：代码注解激活（极少用）
java 复制代码 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ConfigApplication {
    public static void main(String[] args) {
        // 手动指定激活环境
        System.setProperty("spring.profiles.active","dev");
        SpringApplication.run(ConfigApplication.class, args);
    }
}

5.4 特殊技巧：yml单文件多环境配置

yml支持 --- 多文档块语法，可将所有环境配置写在一个yml文件中，适合小型项目：

yaml 复制代码 
# 公共配置
spring:
  application:
    name: single-file-demo
---
# 开发环境
spring:
  profiles: dev
server:
  port: 8080
---
# 测试环境
spring:
  profiles: test
server:
  port: 8081
---
# 生产环境
spring:
  profiles: prod
server:
  port: 80

建议 ：大型项目仍推荐多文件拆分，结构更清晰、维护性更高。

六、高频踩坑总结（必看）

  • yml缩进坑：必须2个空格缩进，禁止Tab，缩进错误直接启动报错

  • yml空格坑 ：key后冒号必须加空格，如port: 8080，无空格配置失效

  • 优先级坑：同目录properties覆盖yml，高路径配置覆盖低路径配置

  • 环境覆盖坑：子环境配置会覆盖公共配置，非完全替换，未配置参数沿用公共配置

  • 中文乱码坑：properties需手动设置编码为UTF-8，yml无此问题

  • 配置绑定坑 ：自定义配置绑定必须添加@ConfigurationProperties 注解，且前缀对应准确

七、企业级最佳实践

  1. 统一配置格式：项目全程使用yml，摒弃properties，统一规范、提升可读性

  2. 严格环境拆分：必须拆分dev/test/prod三套环境，禁止一套配置跑所有环境

  3. 公共配置抽离：通用配置（项目名、扫描路径）放入公共yml，环境独有配置放入子环境文件

  4. 生产环境隔离：生产环境关闭调试日志、弱化权限、开启安全配置，禁止开启DEBUG日志

  5. 部署动态切换 ：服务器部署统一使用命令行指定环境，灵活适配不同服务器

  6. 禁止硬编码：所有变量、端口、地址、密钥全部写入配置文件，代码零硬编码

八、总结

本文全方位讲解了SpringBoot两大核心配置文件，核心要点回顾：

1、properties简洁兼容，yml层级清晰、功能更强，企业开发首选yml；

2、SpringBoot配置有严格的加载优先级，高优先级配置覆盖低优先级配置；

3、Profile多环境配置是企业开发刚需，支持四种动态切换方式，适配开发、测试、部署全场景；

4、遵循配置最佳实践，可彻底解决环境配置混乱、切换出错、硬编码等常见问题。

下一篇：SpringBoot配置加密、配置中心Nacos集成、动态配置实时刷新实战，持续更新中！

九、往期推荐

SpringBoot系列01：一文读懂自动配置原理，新手从零搭建第一个HelloWorld项目

十、下期预告

SpringBoot系列03：核心注解深度剖析：@SpringBootApplication、@Configuration完整源码解读

码字不易，点赞 + 收藏 + 关注，持续更新高质量干货！

热门推荐
012026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf022026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？032026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？04Trae国际版与国内版深度测评：AI原生IDE的双生花05GitHub 镜像站点06飞书长连接_事件订阅（接收消息，审批任务状态变更）07【AI】2026 年具身智能模型和世界模型总结08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析092026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？102026年AI架构实战：彻底解决OpenAI接口超时与封号，Python调用GPT-5.2/Sora2企业级架构详解（附源码+压测报告）