YAML 语法验证器

错误输出说明

验证失败时，错误框包含以下信息：

• 原因 — 错误的通俗描述（如 缩进错误、流结束异常）。
• 行号与列号 — 错误在输入中的精确位置。
• 代码片段 — 解析器提供的上下文，通常包含指向问题字符的 ^ 标记。

常见 YAML 语法错误

• 缩进不一致 — YAML 要求统一使用空格（禁止 Tab）缩进，同级混用 2 格和 4 格缩进会导致解析错误。
• 键后缺少冒号 — key value 是非法的，正确写法为 key: value。
• 特殊字符未加引号 — 值中含有 :、#、[、]、{、} 等字符时，需要用引号包裹或转义。
• Tab 字符 — YAML 禁止用 Tab 缩进，应将所有 Tab 替换为空格。
• 重复键 — 同一映射块中出现重复键在 YAML 1.2 规范中是非法的。

示例：合法 YAML

server:
  host: localhost
  port: 8080
  tls: true

database:
  driver: postgres
  name: myapp
  credentials:
    user: admin
    password: "s3cr3t"

allowed_origins:
  - https://example.com
  - https://api.example.com

示例：非法 YAML（缩进错误）

server:
  host: localhost
   port: 8080   # 错误：多余的空格导致缩进不一致

验证器会报告检测到缩进不一致的行号和列号，便于快速定位并修复问题。

语法合法不等于结构正确

验证器报告的是语法错误。能解析的 YAML 结构也可能不对，所以要看「解析结构」预览。下面的文件里，carrot 少缩进了两个空格：

fruits:
  - apple
vegetables:
- carrot
  - spinach

验证器判定合法，预览显示 "vegetables": ["carrot - spinach"]：下一行被并进了 carrot，成为一个字符串。

YAML 1.1 与 1.2 对值的解读不同

本工具用 js-yaml 4.3.2，遵循 YAML 1.2；Python 常用的 PyYAML 遵循 YAML 1.1。同一份文件得到的数据不同：

文件会被 YAML 1.1 解析器读取时，给 "NO"、"yes"、"0777" 这类值加引号。

常见报错

限制

• 多个文档逐个检查。 用 --- 分隔多个文档的文件（如同时包含 Deployment 和 Service 的 Kubernetes 清单）用 js-yaml 的 loadAll 读取。全部有效时，预览是 JSON 数组，每个文档一项；有文档出错时，逐个列出每个文档的行范围，标明有效或给出错误，出错的 Service 不会掩盖有效的 Deployment。

• 只检查语法。 不按 Kubernetes、GitHub Actions、Docker Compose 的 schema 校验，也不做风格检查。CI 里用 yamllint（yamllint .）。

• 预览是 JSON。 锚点和 << 合并键在预览里已展开，注释不显示。JSON 无法原样显示的值会在预览上方按 JSON Pointer 路径列出，YAML 仍判为有效。下面的 YAML：

  size: .inf
  id: 9007199254740993
  due: 2026-02-31

  显示 JSON 预览没有按原样显示下列值：/size：inf 在 JSON 中没有写法（JSON.stringify 会写成 null）；/id：整数 9007199254740993 超出 ±(2^53 − 1)，JavaScript 会把它四舍五入；/due：2026-02-31 不是有效的日期或时间。预览里这些位置是 null、9007199254740992 和 "2026-03-03T00:00:00.000Z"，不要把它当作原数据复制。预览把负零写成 -0.0，时间戳显示为 UTC（2026-10-01T09:30:00+09:00 显示为 "2026-10-01T00:30:00.000Z"）。

• js-yaml 的处理上限。 js-yaml 4.3.2 遇到嵌套超过 100 层、合并键（<<）累计处理的映射和键超过 10,000 个、一个合并键列出超过 100 个映射的文档会停止。错误信息写明上限，例如「集合嵌套超过 100 层（js-yaml 默认上限）」，并给出行列。