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 AliasYAML 通过定义锚点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 KeyYAML 提供合并键可以将一个映射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 2YAML 使用---将指令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指令表示prefixfoo| |!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数值型\x128-bit\u123416-bit\U0010203032-bitProtective保护型\\反斜杠\\双引号\空格\TAB制表符 TABCC 风格控制字符\0NUL 空字符\aBEL 响铃\bBS 退格\fFF 换页\nLF 换行\rCR 回车\tTAB 制表符\vVTAB 垂直制表符Additional附加\eESC 转义\_NBSP 不间断空格\NNEL 下一行\LLS 行分隔符\PPS 段分隔符更多类型More Types| 标签 | 含义 | | :- | :- | |!!set| 无序集合如{cherries, plums, apples}| |!!omap| 有序映射如[one: 1, two: 2]|与语言无关的标量类型Language-independent Scalar TypesYAML 定义了与编程语言无关的通用标量字面量写法| 字面量 | 类型 | | :- | :- | |{~, null}| 空无值 | |[1234, 0x4D2, 02333]| 十进制整数、十六进制整数、八进制整数 | |[1_230.15, 12.3015e02]| 固定浮点数、指数浮点数 | |[.inf, -.Inf, .NAN]| 无穷大浮点数、负无穷大、非数字 | |{Y, true, Yes, ON}| 布尔真 | |{n, FALSE, No, off}| 布尔假 |由此可知yes/on/y均会被解析为trueno/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、stepssteps是典型的映射序列每个元素包含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与keyvalue为核心使用;/#注释适合轻量简单配置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 原文档中逐一对照验证。【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考