基础设施即代码 / 知识点
YAML 语法速查手册
序列与映射
- <ITEM>使用 - 加空格表示列表元素。
Block Sequence
使用 - 加空格表示列表元素。
所属主题
序列与映射
语法 / 形式
- <ITEM>推荐示例
ports:
- 8080
- 8443关键边界
每个 - 与同级列表元素对齐。
- <KEY>: <VALUE>Sequence 元素可以是 Mapping。
对象列表
Sequence 元素可以是 Mapping。
所属主题
序列与映射
语法 / 形式
- <KEY>: <VALUE>推荐示例
users:
- name: alice
role: admin
- name: bob
role: user关键边界
后续同一对象字段比 - 多一级缩进。
- - <ITEM>Sequence 可以嵌套 Sequence。
列表中嵌套列表
Sequence 可以嵌套 Sequence。
所属主题
序列与映射
语法 / 形式
- - <ITEM>推荐示例
matrix:
- - 1
- 2
- - 3
- 4关键边界
可读性差时优先改用 flow style 或更明确的数据结构。
<KEY>:
- <ITEM>键的值可以是列表。
Mapping 中嵌套 Sequence
键的值可以是列表。
所属主题
序列与映射
语法 / 形式
<KEY>:
- <ITEM>推荐示例
tags:
- linux
- yaml关键边界
配置文件最常见结构之一。
- <KEY>: <VALUE>列表项可以展开为对象。
Sequence 中嵌套 Mapping
列表项可以展开为对象。
所属主题
序列与映射
语法 / 形式
- <KEY>: <VALUE>推荐示例
servers:
- host: a.example.com
port: 443关键边界
对象后续字段要和第一个 key 对齐。
? <KEY>
: <VALUE>使用 ? 显式表示复杂 mapping key。
显式 Mapping Entry
使用 ? 显式表示复杂 mapping key。
所属主题
序列与映射
语法 / 形式
? <KEY>
: <VALUE>推荐示例
? [red, green, blue]
: color-key关键边界
适合复杂 key;普通配置极少需要。
? <NODE>
: <VALUE>Mapping key 本身也可以是复杂节点。
复杂 Key
Mapping key 本身也可以是复杂节点。
所属主题
序列与映射
语法 / 形式
? <NODE>
: <VALUE>推荐示例
? {name: alice, id: 1}
: enabled关键边界
多数应用配置应避免复杂 key,以提升跨语言兼容性。
key: one
key: two同一 Mapping 中重复 key 属于高风险/非法输入。
重复 Key
同一 Mapping 中重复 key 属于高风险/非法输入。
所属主题
序列与映射
语法 / 形式
key: one
key: two推荐示例
port: 8080
port: 9090关键边界
不同解析器可能报错或保留最后一个值;不要依赖覆盖行为。
<MAPPING>YAML presentation 中可以有顺序,但 Mapping 语义不应依赖键顺序。
Key 顺序
YAML presentation 中可以有顺序,但 Mapping 语义不应依赖键顺序。
所属主题
序列与映射
语法 / 形式
<MAPPING>推荐示例
host: localhost
port: 8080关键边界
业务协议若依赖顺序,应改用 Sequence。
Flow Style 行内写法
[<ITEM1>, <ITEM2>]使用方括号在一行表示列表。
Flow Sequence
使用方括号在一行表示列表。
所属主题
Flow Style 行内写法
语法 / 形式
[<ITEM1>, <ITEM2>]推荐示例
ports: [80, 443, 8080]关键边界
适合短列表;复杂嵌套会降低可读性。
{<KEY>: <VALUE>, ...}使用花括号在一行表示 Mapping。
Flow Mapping
使用花括号在一行表示 Mapping。
所属主题
Flow Style 行内写法
语法 / 形式
{<KEY>: <VALUE>, ...}推荐示例
server: {host: localhost, port: 8080}关键边界
适合短对象。
[{...}, {...}]Flow collection 可以嵌套。
Flow 嵌套
Flow collection 可以嵌套。
所属主题
Flow Style 行内写法
语法 / 形式
[{...}, {...}]推荐示例
users: [{name: alice, role: admin}, {name: bob, role: user}]关键边界
长配置优先 block style。
[a, b, c]逗号分隔 flow collection 元素。
Flow 中的逗号
逗号分隔 flow collection 元素。
所属主题
Flow Style 行内写法
语法 / 形式
[a, b, c]推荐示例
items: [a, b, c]关键边界
block style 不使用逗号分隔同级项。
{}Flow style 空对象。
Flow 中的空 Mapping
Flow style 空对象。
所属主题
Flow Style 行内写法
语法 / 形式
{}推荐示例
options: {}关键边界
适合明确表达“空对象”。
[]Flow style 空数组。
Flow 中的空 Sequence
Flow style 空数组。
所属主题
Flow Style 行内写法
语法 / 形式
[]推荐示例
plugins: []关键边界
适合明确表达“空列表”。
[a, b,] / {a: 1,}YAML flow collections 允许尾逗号。
Flow Style 尾逗号
YAML flow collections 允许尾逗号。
所属主题
Flow Style 行内写法
语法 / 形式
[a, b,] / {a: 1,}推荐示例
ports: [80, 443,]关键边界
虽然规范允许,但部分团队 lint 规则可能禁止;统一项目风格。
多行字符串与 Chomping
|保留多行文本中的换行。
Literal Block |
保留多行文本中的换行。
所属主题
多行字符串与 Chomping
语法 / 形式
|推荐示例
script: |
echo hello
echo world关键边界
适合脚本、证书、SQL、配置片段等需要保留换行的内容。
>将多数普通换行折叠为空格。
Folded Block >
将多数普通换行折叠为空格。
所属主题
多行字符串与 Chomping
语法 / 形式
>推荐示例
description: >
This is a long
description.关键边界
适合自然语言长段落;空行和更深缩进行仍有特殊保留规则。
| / >默认保留一个结尾换行。
Clip Chomping 默认
默认保留一个结尾换行。
所属主题
多行字符串与 Chomping
语法 / 形式
| / >推荐示例
text: |
hello关键边界
最终 scalar 通常以一个换行结束。
|- / >-删除结尾换行和尾部空行。
Strip Chomping -
删除结尾换行和尾部空行。
所属主题
多行字符串与 Chomping
语法 / 形式
|- / >-推荐示例
text: |-
hello关键边界
适合 shell 参数、Token-like 文本等不希望尾部 \n 的场景。