Spring Boot application.yml 常见错误示例

用错误示例和正确写法排查 YAML 缩进、profile 覆盖和类型错误。

撰写与维护： ErickPang · 更新于： 2026-07-10

通过错误配置和正确配置对照，排查 application.yml 中缩进、层级、profile、类型和键名导致的配置不生效问题。

错误一：缩进让配置落到错误层级

YAML 使用缩进表达层级。配置看起来只是多了两个空格，实际含义可能已经完全改变。Spring Boot 不一定会在启动时报错，因为 YAML 文件本身仍然是合法格式，只是配置绑定到了错误的位置。

最常见的表现是 server.port、spring.datasource 或 management.endpoints 明明写了，应用运行时却使用默认值。此时应先检查父级和子级是否对齐，而不是先怀疑插件或 Spring Boot 版本。

spring:
  datasource:
  url: jdbc:postgresql://localhost:5432/app
  username: app

# correct
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/app
    username: app

错误二：profile 文件覆盖了基础配置

application.yml 中的值可能被 application-dev.yml、application-test.yml 或 application-prod.yml 覆盖。很多配置不生效不是因为没读取，而是当前激活的 profile 后加载了另一个值。

排查时建议先确认 spring.profiles.active，再搜索同一个配置键在不同文件里是否重复出现。团队项目里尤其要避免把本地调试端口、测试库地址或临时日志级别提交到共享 profile。

确认启动参数、环境变量和 application.yml 中的 active profile
搜索同一个 key 在多个 application-*.yml 中是否重复
保留一处权威配置，避免不同环境文件互相覆盖
用启动日志或 Actuator env 信息确认最终值

错误三：值类型写错

YAML 对数字、布尔值、字符串和列表有自己的解析规则。某些场景下引号不是问题，但当配置绑定到强类型属性时，错误类型可能导致绑定失败或行为不符合预期。

建议对端口、超时时间、布尔开关和列表配置保持一致写法。无法确定时，用最小配置启动一次，并查看 Spring Boot 绑定异常或最终配置值。

server:
  port: 8080
spring:
  main:
    lazy-initialization: false
management:
  endpoints:
    web:
      exposure:
        include:
          - health
          - info

错误四：只检查一个配置来源

Spring Boot 的最终配置不只来自 application.yml。命令行参数、环境变量、外部配置文件和 profile 专用文件都可能参与覆盖。比如文件中是 server.port: 8080，但使用 --server.port=9090 启动时，运行端口应以 9090 为准。

排查时先确定应用实际使用的启动命令和 active profiles，再搜索同一个 key。不要为了验证而公开暴露 Actuator 的 env 或 configprops 端点；在本地环境中，可以结合启动日志、IDE Run Configuration 和针对配置类的测试确认最终值。

# application.yml
server:
  port: 8080

# higher-priority command-line argument
java -jar app.jar --server.port=9090

最小复现与官方依据

最小复现只保留一个配置文件和一个待验证的 key。先在没有 profile、环境变量和额外启动参数的情况下运行；确认基础值生效后，再逐项恢复外部来源。这个过程可以把 YAML 结构错误与配置覆盖问题分开。

Spring Boot 官方外部化配置文档维护完整的 PropertySource 顺序，并说明 YAML 列表不能通过环境变量按索引逐项覆盖。涉及覆盖优先级或复杂集合时，应以当前使用的 Spring Boot 版本文档为准。

本站由 ErickPang 独立维护，与 Spring、JetBrains 或 Broadcom 无官方关联。