随记
YAML 配置文件：可读性强的层级配置
介绍 YAML 映射、序列、标量和多行文本，并说明缩进、隐式类型、重复键与安全加载等常见问题。
发布于 2026年7月24日
YAML 配置文件：可读性强的层级配置
YAML 是一种面向人类阅读的结构化数据格式，常用于 CI/CD、容器编排、基础设施和应用配置。它用缩进表示层级，用短横线表示序列，通常比 JSON 少很多括号和引号，并且原生支持注释。
简洁也带来了隐含规则：缩进、标量类型、版本差异和解析器 Schema 都可能影响结果。YAML 文件“看起来正确”并不足够，必须由目标工具实际解析和校验。
一、完整示例
app:
name: config-demo
debug: false
features:
- search
- cache
server:
host: 127.0.0.1
port: 8080
database:
pool_size: 10
app、server 和 database 对应映射；features 是序列；false、8080 和 10 会按所用 Schema 解析为布尔值与整数。
二、常用语法
映射与序列
映射使用 键: 值，冒号后要留空格：
server:
host: 127.0.0.1
port: 8080
序列中的每项以 - 开始：
features:
- search
- cache
短小结构也可以写成流式形式：
features: [search, cache]
server: {host: 127.0.0.1, port: 8080}
标量、引号与多行文本
YAML 支持字符串、数字、布尔值和空值等标量。为了避免工具把版本号、日期、on、yes 或带前导零的编号解释成其他类型，意图是字符串时应主动加引号：
release: "2026-07-24"
build_code: "0012"
mode: "on"
多行文本常用 | 保留换行，或用 > 折叠为连续文本：
message: |
第一行
第二行
# 开始注释。锚点、别名和合并键能减少重复，但工具支持和合并规则可能不同；公共配置应谨慎使用高级特性。
三、适用场景
YAML 适合：
- 配置由人维护，包含多层映射和较长列表。
- 需要在文件中保留操作说明和上下文注释。
- 目标平台原生采用 YAML，例如许多 CI/CD 与编排工具。
- 声明式资源较多，JSON 的括号和引号会明显干扰阅读。
- 配置模板有独立的 Schema、lint 或部署前校验工具。
只有少量平铺参数时，TOML、INI 或 .env 往往更简单；配置主要由程序交换时，JSON 的严格性更有优势。
四、与其他格式对比
| 对比格式 | YAML 的优势 | YAML 的不足 |
|---|---|---|
| JSON | 注释友好、标记更少，复杂层级更容易阅读 | 缩进敏感，类型和解析器差异更多 |
| TOML | 表达深层对象、对象列表和重复结构更自然 | TOML 的类型边界与配置导向更明确 |
| XML | 文本更紧凑，映射和序列更接近常见数据结构 | 缺少 XML 命名空间及成熟的 XSD 生态 |
| INI | 原生支持数组和深层结构 | 简单分组配置不如 INI 直观 |
YAML 1.2 的目标之一是让 JSON 成为 YAML 的子集，但实际项目仍要确认解析器支持的 YAML 版本和 Schema，不能仅根据扩展名推断行为。
五、常见错误与安全提醒
- 使用空格缩进，不使用 Tab。同级元素必须严格对齐，建议固定为两个空格。
- 为容易误判的字符串加引号。尤其是日期、版本号、开关词、前导零编号和包含
:、#的值。 - 避免重复键。解析器可能拒绝，也可能静默覆盖，结果不可移植。
- 固定 YAML 版本和 Schema。部分旧解析器仍按 YAML 1.1 解释
yes、no、on、off。 - 安全加载不受信任内容。禁用任意对象构造和未知自定义标签，并限制别名展开、文件大小与嵌套深度。
- 不要把模板语法当作 YAML 语法。
${VAR}、{{ value }}等通常属于外层工具，展开顺序和转义规则要单独验证。 - 用目标工具检查。通用 YAML 解析成功，不代表 Kubernetes、CI 平台或应用 Schema 接受所有字段。
六、选型建议
当配置包含深层结构、较多列表，并由人频繁审阅时，YAML 很有吸引力。前提是团队统一缩进、解析器版本与校验工具，并把高级语法控制在必要范围内。
如果配置结构不深但类型要求明确，优先比较 TOML；如果机器互操作性高于注释需求，选择 JSON；若平台已经规定 YAML，则应围绕平台 Schema 建立 lint 和预发布验证。