YAML 基础语法与编写规范详解

YAML（YAML Ain't Markup Language）是一种人性化的数据序列化语言，专为方便人类读写而设计。它常用于配置文件（如 Spring Boot、Kubernetes、Docker Compose 等）以及数据交换场景。

本文将详细介绍 YAML 的核心语法、数据结构及编写规范。

1. 核心规则：缩进与格式

YAML 通过缩进来表示层级关系，这是其最显著的特征，也是新手最容易出错的地方。

严格使用空格缩进 ：严禁使用 Tab 键。不同的编辑器对 Tab 的解析可能不同，混用 Tab 和空格会导致解析器报错。
层级一致性：同一层级的元素必须保持相同的缩进空格数（通常建议使用 2 个或 4 个空格）。
大小写敏感 ：YAML 对键名的大小写敏感，Key 和 key 是两个不同的标识符。

2. 基本数据结构

2.1 对象/映射

使用 key: value 的形式，冒号后必须跟一个空格。

yaml 复制代码

# 简单键值对
path: E:/py_projects/datasets
# 嵌套对象（通过缩进实现）
train:
  images: images/train
  labels: labels/train

2.2 列表/数组

使用短横线加空格 - 开头，表示数组中的一个元素。

yaml 复制代码

# 列表写法
names:
  - Falling
  - Kneeling
  - Sitting

关键概念辨析 ：

原内容中提到的"显式编号形式"实际上是映射结构，而非列表。

yaml 复制代码

# 这不是列表，而是一个键为数字的映射
names:
  0: Falling
  1: Kneeling

在 Python 中，前者会被解析为 list (['Falling', 'Kneeling'])，后者会被解析为 dict ({0: 'Falling', 1: 'Kneeling'})。请根据实际业务需求（如 YOLO 标签字典）选择正确的结构。

2.3 流式风格

YAML 也支持类似 JSON 的内联写法（Flow Style），但在配置文件中通常推荐使用上述的块风格以保持可读性。

yaml 复制代码

# 内联列表
list: [a, b, c]
# 内联映射
map: { key1: value1, key2: value2 }

3. 字符串与注释

3.1 字符串规则

默认情况下，字符串不需要引号。
包含特殊字符（如 :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `````）或以特殊字符开头时，必须使用单引号或双引号包裹。

yaml 复制代码

name: Hard Hat          # 无需引号
title: "Hello: World"   # 包含冒号，需引号包裹
path: 'E:\user\docs'    # 包含反斜杠等路径，建议引号包裹

3.2 注释

以 # 开头，解析器会忽略从 # 开始到行尾的内容。

yaml 复制代码

# 这是整行注释
nc: 6  # 这是行尾注释，常用于解释参数含义

4. 数据类型支持

YAML 支持自动类型推断，无需显式声明类型。

yaml 复制代码

is_valid: true    # 布尔值
count: 100        # 整数
price: 19.99      # 浮点数
parent: ~         # 空值，等同于 Python 的 None

5. 文档分隔符

---：用于在单个文件中分隔多个 YAML 文档。
...：用于标记文档的结束（通常可省略）。

yaml 复制代码

---
# 第一份文档配置
server:
  port: 8080
---
# 第二份文档配置
database:
  host: localhost

6. 实战案例解析

以下是一个典型的目标检测任务配置文件（如 YOLO 格式），展示了上述语法的综合应用：

yaml 复制代码

# 数据集根目录
path: E:/py_projects/safe2/datasets
# 相对于 path 的图像路径
train: images/train
val: images/val
test: images/test
# 类别定义
nc: 6  # 类别数量
# 类别名称映射 (映射结构：键为索引，值为名称)
names:
  0: Falling
  1: Kneeling
  2: Sitting
  3: Sleeping
  4: Standing
  5: Unknown

结构解读：

path, train, val, test 为字符串键值对。
nc 为整型数值。
names 是一个映射，用于存储类别索引与名称的对应关系。

💡 总结与最佳实践

要点	说明
缩进	仅使用空格，禁止 Tab 键。
结构选择	列表用于有序数据，映射用于键值对应（如 ID:名称）。
引号使用	除非包含特殊字符或产生歧义，否则无需为字符串加引号。
可读性优先	配置文件应优先考虑可读性，避免过度使用内联写法。