Spring Boot配置文件详解：properties与YAML格式对比及读取方法

本节目标：看懂 application.properties 与 application.yml 两种配置文件，知道它们怎么互相转换、怎么把值读进代码。

配置文件放在哪

Spring Boot 的配置文件约定放在 src/main/resources 目录下。

文件名固定叫 application，后缀有两种：

application.properties
application.yml（或 .yaml）

项目启动时，Spring Boot 会自动找到它并加载。不用你写任何注册代码。

这就是「约定优于配置」的体现。你只需要按规矩放文件。

properties 格式

properties 是最传统的 Java 配置格式。一行一个键值对：

spring.application.name=hello-app
server.port=8080
app.author=码上学
app.version=1.0.0

结构是扁平的。层级关系靠前缀表达，比如 app.author 和 app.version 都属于 app 这个分组。

写起来简单，几乎没有学习成本。适合键少、结构浅的项目。

YAML 格式

YAML 用缩进表达层级。同样内容写成这样：

spring:
  application:
    name: hello-app

server:
  port: 8080

app:
  author: 码上学
  version: 1.0.0

缩进用空格，不能用 Tab。约定是两级空格。

同一个层级的内容必须对齐。新手最常见的报错，就是缩进不齐。

Note

YAML 里 key: value 冒号后必须跟一个空格。port:8080 是错的，port: 8080 才对。

YAML 字符串与引号

YAML 的值分几种类型，字符串最容易踩坑。

普通字符串不用引号：

app:
  name: hello-app
  message: 这是一个 Spring Boot 应用

值里带特殊字符时，建议加引号。比如带冒号、井号、方括号的值：

app:
  url: "https://example.com/api"
  desc: "内容包含 # 符号"

单引号和双引号有区别：

双引号：支持转义，"\n" 是换行符。
单引号：纯字面量，'\n' 就是反斜杠加 n。

布尔值、数字、null 也各有写法：

app:
  debug: true
  port: 8080
  rate: 1.5
  empty: null

Note

YAML 1.1 规范里 yes、no、on、off 会被当成布尔值。Spring Boot 4.x 用 SnakeYAML 解析，为稳妥起见，布尔值统一写 true / false。

两种格式怎么选

看这张对比表：

对比项	properties	YAML
结构表达	前缀重复，扁平	缩进层级，直观
列表	`[0]` 下标，繁琐	`-` 符号，简洁
多环境	2.4 起支持 `#---` 分隔	原生支持 `---` 分隔
注释	`#`	`#`
学习成本	低	略高

配置项多、层级深的项目，YAML 明显更好读。

不过也有一个注意点：YAML 对缩进敏感，复制粘贴时容易乱。

官方建议：整个项目只用一种格式，不要混用。

Warning

如果同一位置同时放了 application.properties 和 application.yml，properties 优先，yml 会被忽略。排查问题时先确认有没有重复文件。

占位符引用

两种格式都支持 ${...} 占位符。可以引用已定义的键：

app.name=hello-app
app.description=${app.name} is a Spring Boot application

也可以给默认值，冒号后面跟默认值：

app.description=${app.name} is written by ${author:码上学}

author 不存在时，会使用默认值「码上学」。

占位符还能引用环境变量和系统属性，这个在第 12 章细讲。

把配置读进代码

配置写好了，代码里怎么拿？三种方式：

方式一：@Value 注解

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Value("${app.name}")
    private String appName;

    @GetMapping("/name")
    public String name() {
        return appName;
    }
}

适合单个零散属性。属性找不到会启动失败，建议带默认值：

@Value("${app.name:hello-app}")
private String appName;

方式二：Environment 对象

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.env.Environment;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Autowired
    private Environment env;

    @GetMapping("/port")
    public String port() {
        return env.getProperty("server.port");
    }
}

适合动态拼键名、批量遍历的场景。

方式三：@ConfigurationProperties

把一组属性绑定成对象。类型安全、可校验，是官方推荐的主力方式。下一章专门讲它。

配置文件的搜索位置

application.properties 和 application.yml 不止 classpath 一处。

Spring Boot 会从 classpath 和当前目录等多个位置按固定顺序搜索，后找到的覆盖先找到的。完整位置列表在第 12 章。

核心结论就一句：jar 包外部的配置文件，天然能覆盖 jar 内部的默认值。

部署时的常见做法：

/app
  hello-app.jar
  config/
    application.yml

运维改配置不用重新打包，改完重启即可。

本机调试小技巧

启动时加 --debug，能看到配置相关的调试信息（条件报告解读见 §6）：

mvn spring-boot:run -Dspring-boot.run.arguments=--debug

打包后运行也一样：

java -jar hello-app.jar --debug

配置没生效时，先看这里的输出。

转换练习

同一份配置，两种格式对照着写一遍，印象最深。

properties 写法：

spring.application.name=hello-app
server.port=8081
app.author=码上学
app.features[0]=logging
app.features[1]=metrics

YAML 等价写法：

spring:
  application:
    name: hello-app

server:
  port: 8081

app:
  author: 码上学
  features:
    - logging
    - metrics

规则就两条：

点号前缀变成缩进层级。
[0]、[1] 下标变成 - 列表项。

小结

配置文件放 src/main/resources，名字固定为 application。
properties 扁平简单，YAML 层级清晰。
两种格式等价，别在同一位置混用。
${...} 占位符支持引用和默认值。
YAML 的引号、布尔值有自己的规则。
配置文件有多个搜索位置，外部文件能覆盖 jar 内部。
读配置有 @Value、Environment、@ConfigurationProperties 三条路。

下一章，把 @ConfigurationProperties 彻底讲透。

配置文件：properties 与 YAML

配置文件放在哪

properties 格式

YAML 格式

YAML 字符串与引号

两种格式怎么选

占位符引用

把配置读进代码

配置文件的搜索位置

本机调试小技巧

转换练习

小结