配置基础

约 712 字大约 2 分钟

布欧-Lewyon

2026-05-15

Spring Boot 支持 .properties 和 .yml（YAML）两种配置文件格式，并定义了严密的配置优先级。

properties 与 YAML

application.properties：

server.port=9090
server.servlet.context-path=/demo

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver

等价的 application.yml：

server:
  port: 9090
  servlet:
    context-path: /demo

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver

YAML 的层级结构更清晰，是社区主流选择。注意缩进必须使用空格，不能使用 Tab。

如果同时存在 application.properties 和 application.yml，properties 优先级高于 YAML——同名属性以 properties 中的值为准。生产建议只使用一种格式，避免混淆。

配置优先级

Spring Boot 按以下优先级（从高到低）应用配置，高优先级覆盖低优先级：

命令行参数：--server.port=9000
JNDI 属性（java:comp/env）
系统环境变量（如 SERVER_PORT）
application-{profile}.properties/yml（Profile 专用文件）
application.properties/yml（主文件）
@PropertySource 注解加载的资源

例如，同时存在以下配置：

# application.yml
server:
  port: 8080

启动时传入 --server.port=9000，最终端口为 9000。

环境变量映射

Spring Boot 支持将环境变量自动转换为配置属性，规则是：点号变下划线、小写变大写、连字符变下划线：

环境变量	对应配置属性
`SERVER_PORT`	`server.port`
`SPRING_DATASOURCE_URL`	`spring.datasource.url`
`LOGGING_LEVEL_COM_EXAMPLE`	`logging.level.com.example`

这使容器化场景可以完全通过环境变量注入配置，无需挂载配置文件。

生产意识：环境变量名长度超过特定平台限制时（如 Windows 对 env 长度有限制），考虑使用配置文件挂载替代。Kubernetes 下更推荐通过 ConfigMap 或 Secret 挂载配置文件而非堆砌环境变量——一次性注入上百个 env 会显著增加 Pod 启动延迟并难以排错。

spring.config.import

从 Spring Boot 2.4+（延续到 3.x）引入 spring.config.import，允许引入外部配置文件：

spring:
  config:
    import:
      - classpath:db-config.yml
      - file:/etc/app/optional-config.yml  # 外部文件系统路径

可用前缀：

classpath:：从 classpath 加载
file:：从文件系统加载
optional:：文件不存在时不报错，如 optional:file:/etc/app/config.yml

小结

YAML 用层级结构组织配置，缩进须用空格。
配置优先级：命令行参数 > 环境变量 > Profile 文件 > 主文件。
环境变量名自动映射为点号分隔的属性键，适合容器部署。
spring.config.import 支持从文件系统或 classpath 引入外部配置。
易错：YAML 中 port: 后必须有一个空格再写值；Tab 缩进会导致解析错误。spring.config.import 路径错误时应用启动失败，用 optional: 前缀可以让文件缺失优雅降级。
思考任务：在 application.yml 中配置 server.port=8081，然后通过命令行 --server.port=8082 启动，确认最终生效端口。

上一节：推荐工程结构

下一节：多环境与 Profile