类型强制转换陷阱

• yes、no、on、off、true、false → 布尔值；若需表示字面量字符串，请加引号："yes"
• NO（挪威国家代码）→ 在 YAML 1.1 中被解析为 false；国家代码务必加引号
• 1.0 → 浮点数，1 → 整数；版本号应加引号："1.0"
• 010 → 在 YAML 1.1 中被解析为八进制（即十进制的 8）；请加引号或显式使用 0o10
• null、~、空值 → null；若需表示字面量字符串，请加引号："null"、"~"
• .inf、-.inf、.nan → 特殊浮点值；若需表示字面量字符串，请加引号

缩进

• 仅允许使用空格——禁止使用制表符（tab），否则会导致解析错误
• 文档内缩进宽度必须一致——通常约定使用 2 个空格
• 序列项的短横线 - 算作缩进的一部分——嵌套内容需在该短横线后的空格之后对齐

字符串

• 冒号后紧跟空格（: ）会触发键值对解析——若字符串本身包含 : ，须加引号
• # 在未加引号时始终表示注释起始——若字符串含 #，须加引号
• 未加引号的字符串首尾空格会被自动去除——如需保留，须加引号
• 以 @、`、*、&、!、|、>、{、[、% 开头的字符串须加引号

多行字符串

• | 表示字面量块（literal block），保留所有换行；> 表示折叠块（folded block），将各行用空格连接
• 尾部换行处理：|- 和 >- 会去除末尾换行；|+ 和 >+ 会保留末尾的空白行
• 块中首行内容的缩进量决定整个块的基准缩进——请保持一致性

结构

• 重复键：YAML 规范规定以最后一次出现为准，但部分解析器会报错——应避免键重复
• 锚点 &name 与别名 *name 可减少重复内容——但别名无法覆盖锚点定义的值
• 文档分隔符 --- 开启新文档；... 结束当前文档——在文档流（stream）中尤为有用
• 两个 --- 之间的空文档是合法的，但通常属于非预期行为

注释

• # 仅在行首或前导空白之后有效——key:value#comment 中不包含注释
• 多行块标量（multiline block scalar）后不支持内联注释——注释将作用于下一行
• YAML 不支持多行注释语法——每行注释均需以 # 开头

兼容性

• YAML 1.1 与 1.2 的差异：布尔字面量（如 yes/no）、八进制语法等存在区别——需明确所用解析器支持的 YAML 版本
• JSON 是有效的 YAML 1.2，但 YAML 特有特性（如锚点、多行字符串）无法无损 round-trip 回 JSON
• 部分解析器对嵌套深度或文件大小有限制——请使用预期规模的数据进行测试