基础设施即代码 / 知识点
YAML 语法速查手册
基础结构与缩进
<KEY>: <VALUE>使用冒号加空格表示映射键值对。
键值映射
使用冒号加空格表示映射键值对。
所属主题
基础结构与缩进
语法 / 形式
<KEY>: <VALUE>推荐示例
name: anystack关键边界
冒号后通常需要分隔空白;key:value 在 block mapping 中不要当作标准键值写法。
<KEY>:
<CHILD>: <VALUE>通过缩进表达层级关系。
嵌套映射
通过缩进表达层级关系。
所属主题
基础结构与缩进
语法 / 形式
<KEY>:
<CHILD>: <VALUE>推荐示例
server:
host: 127.0.0.1
port: 8080关键边界
同一层级必须保持一致缩进。
<SPACES><CONTENT>YAML 的 block structure 依赖空格缩进。
使用空格缩进
YAML 的 block structure 依赖空格缩进。
所属主题
基础结构与缩进
语法 / 形式
<SPACES><CONTENT>推荐示例
app:
name: demo
port: 8080关键边界
不要使用 Tab 作为结构缩进字符;团队建议统一 2 个空格。
key1: value1
key2: value2同一个 mapping 中的键保持相同缩进。
同级键保持对齐
同一个 mapping 中的键保持相同缩进。
所属主题
基础结构与缩进
语法 / 形式
key1: value1
key2: value2推荐示例
host: localhost
port: 8080关键边界
错一格就可能改变数据结构或直接解析失败。
{}表示一个空映射对象。
空 Mapping
表示一个空映射对象。
所属主题
基础结构与缩进
语法 / 形式
{}推荐示例
metadata: {}关键边界
等价于“存在 metadata,但里面没有键”。
[]表示一个空序列。
空 Sequence
表示一个空序列。
所属主题
基础结构与缩进
语法 / 形式
[]推荐示例
items: []关键边界
与 null、缺失字段是三种不同语义。
<KEY>:键后没有显式值时形成空 scalar,schema 常解析为 null。
空值节点
键后没有显式值时形成空 scalar,schema 常解析为 null。
所属主题
基础结构与缩进
语法 / 形式
<KEY>:推荐示例
description:关键边界
业务上若需要明确空字符串应写 description: ""。
null / ~在 YAML core schema 中表示 null。
显式 Null
在 YAML core schema 中表示 null。
所属主题
基础结构与缩进
语法 / 形式
null / ~推荐示例
deletedAt: null关键边界
~ 也可表示 null,但可读性通常不如 null。
'' / ""显式表示长度为 0 的字符串。
字符串空值
显式表示长度为 0 的字符串。
所属主题
基础结构与缩进
语法 / 形式
'' / ""推荐示例
description: ""关键边界
不要和 key: 的 null 语义混淆。
标量与引号
plain text不加引号的普通标量。
Plain Scalar
不加引号的普通标量。
所属主题
标量与引号
语法 / 形式
plain text推荐示例
name: anystack关键边界
简单字符串最清晰,但包含特殊字符或容易被解析成类型时应加引号。
'<TEXT>'单引号字符串几乎不处理反斜杠转义。
单引号字符串
单引号字符串几乎不处理反斜杠转义。
所属主题
标量与引号
语法 / 形式
'<TEXT>'推荐示例
pattern: '\d+\.\d+'关键边界
适合正则、Windows 路径等大量反斜杠文本。
''单引号字符串内部用两个单引号表示一个 '。
单引号内写单引号
单引号字符串内部用两个单引号表示一个 '。
所属主题
标量与引号
语法 / 形式
''推荐示例
message: 'YAML isn''t JSON'关键边界
不是使用 \' 转义。
"<TEXT>"支持 YAML 定义的反斜杠 escape sequences。
双引号字符串
支持 YAML 定义的反斜杠 escape sequences。
所属主题
标量与引号
语法 / 形式
"<TEXT>"推荐示例
message: "line1\nline2"关键边界
需要 \n、\t、Unicode 转义时使用双引号。
\n / \r / \t在双引号标量中表示换行、回车、Tab。
双引号换行转义
在双引号标量中表示换行、回车、Tab。
所属主题
标量与引号
语法 / 形式
\n / \r / \t推荐示例
text: "a\nb\tc"关键边界
单引号中这些通常只是普通反斜杠文本。
\xNN / \uNNNN / \UNNNNNNNN在双引号字符串中通过码点转义字符。
Unicode 转义
在双引号字符串中通过码点转义字符。
所属主题
标量与引号
语法 / 形式
\xNN / \uNNNN / \UNNNNNNNN推荐示例
smile: "\u263A"关键边界
只在双引号 style 中使用。
'<TEXT>: <TEXT>'字符串里出现 : 时建议加引号。
需要引号的冒号文本
字符串里出现 : 时建议加引号。
所属主题
标量与引号
语法 / 形式
'<TEXT>: <TEXT>'推荐示例
message: 'status: ready'关键边界
未加引号可能被解释成 mapping 结构。
'<TEXT> # <TEXT>'字符串里出现由空白分隔的 # 时应加引号。
需要引号的井号文本
字符串里出现由空白分隔的 # 时应加引号。
所属主题
标量与引号
语法 / 形式
'<TEXT> # <TEXT>'推荐示例
color: '#ff6600'关键边界
Plain scalar 中空白后的 # 会开始注释。
'<DIGITS>'看起来像数字但业务上必须保留字符串时加引号。
数字样式字符串
看起来像数字但业务上必须保留字符串时加引号。
所属主题
标量与引号
语法 / 形式
'<DIGITS>'推荐示例
zipCode: '00123'关键边界
避免解析器把它当数值并丢失前导零。
'true' / 'false'业务需要字面字符串时显式加引号。
布尔样式字符串
业务需要字面字符串时显式加引号。
所属主题
标量与引号
语法 / 形式
'true' / 'false'推荐示例
featureFlag: 'false'关键边界
否则 core schema 通常解析为 Boolean。
'<DATE_OR_TIME>'业务上要求严格字符串时给日期/时间加引号。
日期时间样式字符串
业务上要求严格字符串时给日期/时间加引号。
所属主题
标量与引号
语法 / 形式
'<DATE_OR_TIME>'推荐示例
versionDate: '2026-08-27'关键边界
不同 schema/解析库对 timestamp 的隐式解析能力存在差异。