YAML 配置语法完全指南：基于 Reference 项目备忘清单的标量、集合与锚点速查-育师

YAML 配置语法完全指南：基于 Reference 项目备忘清单的标量、集合与锚点速查

【免费下载链接】reference面向开发者的技术速查清单（Cheat Sheets）集合，整理常见技术、工具与开发流程，帮助快速查阅关键信息，提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference

本篇技术指南以本仓库的 YAML 备忘清单为骨架，系统讲解 YAML 作为一种面向人类读写的数据序列化语言的全部核心语法：从标量类型、注释、多行字符串，到锚点/别名与继承、序列与映射的各种嵌套组合，再到文档/收集/标量指标符与转义码速查。通过阅读本文，你将能够独立读懂并编写 Docker Compose、Ansible Playbook、GitHub Actions 工作流等一切基于 YAML 的配置文件，并理解这些语法在实际项目（如本仓库的 .github/workflows/ci.yml）中如何被真实使用。

入门：理解与编写 YAML 的基本规则

介绍

YAML 是一种数据序列化语言，其设计目标就是供人类直接读写。在开始编写 YAML 之前，需要牢记以下五条基础规则：

YAML 不允许使用制表符（Tab），缩进必须使用空格；
元素部分之间必须有空格，例如冒号、横线等标记与值之间要留白；
YAML 区分大小写，True、TRUE与true含义不同；
以.yaml或.yml扩展名结束您的 YAML 文件；
YAML 是 JSON 的超集，任何合法的 JSON 文档同时也是合法的 YAML 文档；
Ansible Playbook 就是 YAML 文件，Docker Compose、GitHub Actions、Kubernetes 清单等现代 DevOps 工具链同样以 YAML 为配置基础。

在本仓库中，.github/workflows/ci.yml 就是一份真实的 YAML 应用实例——它定义了 Reference 项目的 CI 构建、Docker 镜像发布等完整流水线；.github/ISSUE_TEMPLATE/bug-report.yml 则是用 YAML 描述 GitHub Issue 表单结构的另一个典型场景。

标量类型（Scalar Types）

标量是 YAML 中最基本的数据单元，即单个值。YAML 会根据值的字面写法自动推断其类型：

n1: 1 # 整数 n2: 1.234 # 浮点 s1: 'abc' # 字符串 s2: "abc" # 字符串 s3: abc # 字符串 b: false # 布尔类型 d: 2015-04-05 # 日期类型

等效的 JSON

{ "n1": 1, "n2": 1.234, "s1": "abc", "s2": "abc", "s3": "abc", "b": false, "d": "2015-04-05" }

注意两个关键点：

使用空格缩进，且元素部分之间必须有空间；
未加引号的abc会被解析为字符串，日期2015-04-05在多数实现中会被解析为日期类型（序列化回 JSON 时表现为字符串）。如果想强制某个值始终作为字符串处理，请显式使用单引号或双引号包裹。

变量：锚点与别名（Anchor & Alias）

YAML 通过&定义锚点（anchor），通过*引用别名（alias），从而在同一文档内"复用"某个值：

some_thing: &VAR_NAME foobar other_thing: *VAR_NAME

等效的 JSON

{ "some_thing": "foobar", "other_thing": "foobar" }

这里&VAR_NAME把值foobar记录到名为VAR_NAME的锚点中，随后*VAR_NAME将其展开。这种机制在需要多处引用同一常量时非常实用，例如 CI 中复用同一份依赖缓存路径。

注释

YAML 使用#表示注释，注释可以独立成行，也可以跟在行尾：

# A single line comment example # block level comment example # comment line 1 # comment line 2 # comment line 3

例如本仓库 .github/workflows/ci.yml 中就有大量注释行（如# Or、# Create Docker Image等），用来向读者解释不同命令的等价用法，注释内容不会被 YAML 解析器读取。

多行字符串：保留换行（Literal Block）

使用块标量指示符|（pipe）可以让多行文本保留原有换行符：

description: | hello world

等效的 JSON

{"description": "hello\nworld\n"}

|之后的每一行都会成为字符串内容，换行被保留，且字符串末尾会附加一个换行符。

多行字符串：折叠换行（Folded Block）

使用折叠标量指示符>（greater-than）则会将多行文本折叠为单行，换行符被空格替代：

description: > hello world

等效的 JSON

{"description": "hello world\n"}

>适合书写较长的段落型文本，如 README 描述、注释性说明等，既保持源码中的排版美观，又得到连续的字符串。两者的换行处理差异可通过追加 chomp 修饰符进一步微调（详见后文"标量指标"小节）。

继承：合并键（Merge Key）

YAML 提供<<合并键，可以将一个映射（map）的键值对合并进另一个映射，实现类似"继承"的效果：

parent: &defaults a: 2 b: 3 child: <<: *defaults b: 4

等效的 JSON

{ "parent": { "a": 2, "b": 3 }, "child": { "a": 2, "b": 4 } }

注意child中显式定义的b: 4覆盖了从parent继承来的b: 3，而a: 2被继承保留。这正是"默认值 + 局部覆盖"配置模式的语法基础，在 Kubernetes、Compose 多环境配置中被广泛使用。

参考：复用整个集合（Alias 引用序列）

锚点不仅限于标量，也可以锚定一个完整的集合，再用别名整体复用：

values: &ref - Will be - reused below other_values: i_am_ref: *ref

等效的 JSON

{ "values": [ "Will be", "reused below" ], "other_values": { "i_am_ref": [ "Will be", "reused below" ] } }

两份文件：多文档流

一个 YAML 文件中可以通过---分隔出多个独立文档：

--- document: this is doc 1 --- document: this is doc 2

YAML 使用---将指令（directives）与文档内容分开。解析器会依次读取每个由---分隔的文档；对应地，...用于显式标识文档结束。在多文档流场景（如kubectl apply -f合并多个资源、Fluentd 多配置）中这一特性尤其常用。

YAML Collections：序列与映射的组合

YAML 的集合（Collections）只有两大类：序列（Sequence，即数组/列表）与映射（Mapping，即哈希/字典），其余一切都是二者的嵌套组合。

序列（Sequence）

以-开头表示序列中的每个条目：

- Mark McGwire - Sammy Sosa - Ken Griffey

等效的 JSON

[ "Mark McGwire", "Sammy Sosa", "Ken Griffey" ]

映射（Mapping）

以key: value形式表示键值对：

hr: 65 # Home runs avg: 0.278 # Batting average rbi: 147 # Runs Batted In

等效的 JSON

{ "hr": 65, "avg": 0.278, "rbi": 147 }

映射到序列

映射的值可以是序列，既可以使用块式（每行一个-），也可以使用内联式（方括号[]）：

attributes: - a1 - a2 methods: [getter, setter]

等效的 JSON

{ "attributes": ["a1", "a2"], "methods": ["getter", "setter"] }

映射序列（对象数组）

序列的每个条目本身又是一个映射，这是最常见的"对象列表"形态，注意第三个条目演示了-独占一行、键值对另起一行的写法：

children: - name: Jimmy Smith age: 15 - name: Jimmy Smith age: 15 - name: Sammy Sosa age: 12

等效的 JSON

{ "children": [ {"name": "Jimmy Smith", "age": 15}, {"name": "Jimmy Smith", "age": 15}, {"name": "Sammy Sosa", "age": 12} ] }

这种结构在现实配置中无处不在：例如 .github/workflows/ci.yml 中的steps就是一个映射序列，每个 step 都有uses、with、run等键；.github/ISSUE_TEMPLATE/bug-report.yml 中的body同样是映射序列，每一项都包含type、id、attributes、validations等键。

序列的序列（嵌套数组）

序列的元素可以是另一个序列，块式与内联式（[]）可以混用：

my_sequences: - [1, 2, 3] - [4, 5, 6] - - 7 - 8 - 9 - 0

等效的 JSON

{ "my_sequences": [ [1, 2, 3], [4, 5, 6], [7, 8, 9, 0] ] }

映射的映射（嵌套字典）

映射的值也可以整体内联在花括号{}中：

Mark McGwire: {hr: 65, avg: 0.278} Sammy Sosa: { hr: 63, avg: 0.288 }

等效的 JSON

{ "Mark McGwire": { "hr": 65, "avg": 0.278 }, "Sammy Sosa": { "hr": 63, "avg": 0.288 } }

嵌套集合（综合示例）

将序列与映射自由嵌套，即可表达任意深度的结构化数据：

Jack: id: 1 name: Franc salary: 25000 hobby: - a - b location: {country: "A", city: "A-A"}

等效的 JSON

{ "Jack": { "id": 1, "name": "Franc", "salary": 25000, "hobby": ["a", "b"], "location": { "country": "A", "city": "A-A" } } }

无序集（Set）

通过显式标签!!set可以定义无序集合：

set1: !!set ? one ? two set2: !!set {'one', "two"}

等效的 JSON

{ "set1": {"one": null, "two": null}, "set2": {"one": null, "two": null} }

集合在底层表示为一个映射，其中每个键都与一个空值（null）相关联。这里?作为关键指标符，表示"只给出键"的条目。

有序映射（Ordered Map）

通过显式标签!!omap可以定义保持插入顺序的映射，每个条目是一个单键映射：

ordered: !!omap - Mark McGwire: 65 - Sammy Sosa: 63 - Ken Griffy: 58

等效的 JSON

{ "ordered": [ {"Mark McGwire": 65}, {"Sammy Sosa": 63}, {"Ken Griffy": 58} ] }

YAML 参考：指标符与核心类型速查

条款（Terminology）

先统一术语，避免歧义：

序列（Sequence）又名数组（Array）或列表（List）；
标量（Scalar）又名字符串或数字；
映射（Mapping）又名哈希（Hash）或字典（Dictionary）。

本节速查内容基于 YAML.org 官方参考卡（refcard）整理，与 INI 备忘清单、TOML 备忘清单互为补充，适合作为编码时的案头速查。

文档指标（Document Indicators）

| 指标 | 含义 | | :- | :- | |%| 指令指标（directive indicator） | |---| 文档标题（document header） | |...| 文档终结者（document terminator） |

收集指标（Collection Indicators）

| 指标 | 含义 | | :- | :- | |?| 关键指标（key indicator） | |:| 价值指标（value indicator） | |-| 嵌套系列条目指示器（nested series entry indicator） | |,| 单独的内联分支条目（separate inline branch entries） | |[]| 环绕串联系列分支（surround inline series branch） | |{}| 环绕在线键控分支（surround inline keyed branch） |

别名指标（Alias Indicators）

| 指标 | 含义 | | :- | :- | |&| 锚属性（anchor property） | |*| 别名指示符（alias indicator） |

特殊键（Special Keys）

| 指标 | 含义 | | :- | :- | |=| 默认"值"映射键（default "value" mapping key） | |<<| 合并来自另一个映射的键（merge keys from another mapping） |

<<即为前文"继承"小节使用的合并键；=用于在带键的映射中显式指定默认值条目。

标量指标（Scalar Indicators）

| 指标 | 含义 | | :- | :- | |''| 环绕内联未转义标量（surround in-line unescaped scalar） | |"| 环绕内嵌转义标量（surround in-line escaped scalar） | |\|| 块标量指示器（literal block scalar indicator） | |>| 折叠标量指示器（folded block scalar indicator） | |-| 剥离 chomp 修饰符（\|-或>-，去掉末尾换行） | |+| 保留 chomp 修饰符（\|+或>+，保留所有末尾换行） | |1-9| 显式缩进修饰符（\|1或>2），修饰符可以组合（\|2-、>+1） |

chomp 修饰符直接控制多行字符串结尾换行的处理：默认行为是保留单个换行；追加-则剥离结尾换行；追加+则完整保留所有结尾换行。例如description: >-常用于在 GitHub Actions 的run多行脚本后避免多余空行。

标签属性（Tag Properties，通常未指定）

| 标签 | 含义 | | :- | :- | |none| 未指定的标签（由应用程序自动解析） | |!| 非特定标签（默认情况下，解析为!!map/!!seq/!!str） | |!foo| 主要（primary）标签，按照惯例表示本地!foo标记 | |!!foo| 次要（secondary）标签，按照惯例表示tag:yaml.org,2002:foo| |!h!foo| 需要%TAG !h! <prefix>指令，表示<prefix>foo| |!<foo>| 逐字标记（verbatim tag，始终表示foo） |

杂项指标（Miscellaneous Indicators）

| 指标 | 含义 | | :- | :- | |#| 一次性评论指示器（comment indicator） | |`、@| 两者都保留供将来使用（reserved for future use） |

核心类型（Core Types，默认自动标签）

| 标签 | 含义 | | :- | :- | |!!map| 哈希表、字典、映射（Hash table, dictionary, mapping） | |!!seq| 列表、数组、元组、向量、序列（List, array, tuple, vector, sequence） | |!!str| Unicode 字符串 |

这是 YAML 自动类型解析的基础：普通键值对默认为!!map，-列表默认为!!seq，未加引号的文本默认为!!str。

转义码（Escape Codes）

双引号包裹的字符串支持多种转义序列：

Numeric（数值型）

\x12（8-bit）
\u1234（16-bit）
\U00102030（32-bit）

Protective（保护型）

\\（反斜杠\）
\"（双引号"）
\（空格）
\<TAB>（制表符 TAB）

C（C 风格控制字符）

\0（NUL 空字符）
\a（BEL 响铃）
\b（BS 退格）
\f（FF 换页）
\n（LF 换行）
\r（CR 回车）
\t（TAB 制表符）
\v（VTAB 垂直制表符）

Additional（附加）

\e（ESC 转义）
\_（NBSP 不间断空格）
\N（NEL 下一行）
\L（LS 行分隔符）
\P（PS 段分隔符）

与语言无关的标量类型（Language-independent Scalar Types）

YAML 定义了与编程语言无关的通用标量字面量写法：

| 字面量 | 类型 | | :- | :- | |{~, null}| 空（无值） | |[1234, 0x4D2, 02333]| 十进制整数、十六进制整数、八进制整数 | |[1_230.15, 12.3015e+02]| 固定浮点数、指数浮点数 | |[.inf, -.Inf, .NAN]| 无穷大（浮点数）、负无穷大、非数字 | |{Y, true, Yes, ON}| 布尔真 | |{n, FALSE, No, off}| 布尔假 |

由此可知：yes/on/y均会被解析为true，no/off/n均会被解析为false；数字字面量支持0x十六进制、0前缀八进制、下划线分隔以及科学计数法——这也是为什么"布尔值必须用小写true/false才会被大多数解析器识别"的原因。

仓库实战：YAML 语法在本项目中的真实落地

理论学习之外，本仓库自身的构建与协作体系就是 YAML 语法的最佳实践样本。

GitHub Actions 工作流：CI 流水线的 YAML 表达

.github/workflows/ci.yml 完整展现了 YAML 在 CI/CD 中的典型用法：

顶层键：name（工作流名）、on（触发条件）、jobs（任务集合）；
嵌套集合：jobs.build下嵌套runs-on、steps；steps是典型的映射序列，每个元素包含uses（引用 action）、with（参数映射）、run（执行命令）、name（步骤名）；
多行字符串：步骤中用|块标量书写多行 Shell 脚本（如生成dist/README.md的cat << "EOF" ... EOF段落）；
锚点式复用：with: github_token: ${{ secrets.GITHUB_TOKEN }}这类键值对在多处重复出现，若需进一步去重，即可用前文介绍的&/*锚点机制。

这份文件同时是"映射的映射"（with内嵌套registry-url等键）、"序列的序列"（platforms: linux/amd64,linux/arm64作为内联序列）以及注释使用的综合示范。

GitHub Issue 模板：YAML 表单（form schema）定义

.github/ISSUE_TEMPLATE/bug-report.yml 与 .github/ISSUE_TEMPLATE/cheatsheet-request.yml 展示了 YAML 的另一个实战方向——结构化表单定义：

name、description、title、labels（内联序列['request']）、assignees等标量与序列；
body是映射序列，每个元素以type区分表单控件（markdown、input、checkboxes、textarea），并通过attributes映射描述label、description、placeholder，通过validations映射声明required布尔值。

这正是前文"标量类型（布尔、字符串）""映射序列""嵌套集合"诸节的综合应用——阅读完前面的语法，你便能完全读懂这类模板文件的每一行。

配置生态横向对比

YAML 常与 INI、TOML 并称为三大人类友好配置文件格式，本仓库对三者均有配套速查文档：

YAML 备忘清单：本文主体，强调缩进敏感、锚点/别名与继承、丰富的类型标签；
INI 备忘清单：以节（section）与key=value为核心，使用;/#注释，适合轻量简单配置；
TOML 备忘清单：以[table]与key = "value"为核心，类型明确、无缩进约束，适合需要强类型的应用配置。

在选型时可以参考：需要表达复杂嵌套与复用（如 CI 工作流、编排清单）选 YAML；配置简单扁平选 INI；追求严格类型与可预测性选 TOML。例如本仓库的 netlify.toml 即采用 TOML 描述构建配置（[build]表 +command/publish键），而 CI 流水线则选择 YAML，两种格式各司其职。

总结

YAML 的核心学习路径可以概括为三条主线：

标量：掌握整数、浮点、字符串、布尔、日期、null 的自动推断规则，以及|（保留换行）、>（折叠换行）和 chomp 修饰符对多行字符串的精确控制；
集合：理解序列、映射及两者任意嵌套组合的六种基本形态，同时会用[]、{}内联写法简化表达；
复用机制：熟练运用&锚点、*别名与<<合并键，实现值复用与"默认值 + 覆盖"的继承式配置。

在此基础上，对照 .github/workflows/ci.yml、.github/ISSUE_TEMPLATE/bug-report.yml 等仓库内真实文件反复阅读，即可快速建立"看到 YAML 就能读懂、需要配置就能写出"的实战能力。本文所有语法条目均可在 docs/yaml.md 原文档中逐一对照验证。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考