YAML / JSON 互转工具

YAML（YAML Ain't Markup Language）是配置文件的首选格式， 优势是支持注释（#）、可读性高、支持多文档（--- 分隔）、 支持锚点 / 别名复用，劣势是解析复杂、缩进敏感、类型推断有陷阱。 JSON（JavaScript Object Notation）是数据交换的标准格式， 优势是严格类型、解析快、与 API 兼容、所有语言原生支持， 劣势是不支持注释、体积较大、可读性稍差。 经验法则：人写的配置文件用 YAML，机器交换的数据用 JSON。 典型场景：Kubernetes / CI-CD / OpenAPI 用 YAML，REST API / 数据库存储用 JSON。

YAML 的核心规则是用空格缩进表示层级，不能用 Tab。这是 YAML 最常见的踩坑点。 具体规则：

• 只能用空格，不能用 Tab（\t）。若编辑器把 Tab 展开为空格则可用
• 缩进必须一致，同一层级的元素缩进空格数必须相同
• 缩进空格数不强制（2 / 4 / 8 均可），但同级元素必须对齐
• 子节点缩进必须大于父节点，例如父节点缩进 2，子节点至少缩进 4
• 列表项（- item）的 - 后必须有空格

本工具解析 YAML 时严格遵循此规则，遇到 Tab 缩进会报错「Tabs are not allowed for indentation」， 并指出错误行号。建议在编辑器中设置「将 Tab 转为空格」避免此问题。

这取决于 YAML 解器使用的 schema 版本：YAML 1.1（如 PyYAML、libyaml、Ruby psych） 会把 yes / no / on / off / y / n 解析为布尔值；YAML 1.2（较新标准，本工具基于 js-yaml v4）已移除此规则，保留为字符串。

# YAML 1.1 解析器（PyYAML 等）会转为布尔
# YAML 1.2 解析器（本工具）保留为字符串
enabled: yes      # 1.1: true   |  1.2: "yes"
answer: no         # 1.1: false  |  1.2: "no"

# 跨解析器统一保留为字符串，请用引号包裹
enabled: "yes"
answer: "no"

本工具基于 YAML 1.2，yes / no 会保留为字符串。但若你的 YAML 文件 会被 Python（PyYAML）、Ruby、C（libyaml）等 YAML 1.1 解析器读取，建议用引号包裹 避免跨解析器行为不一致。本工具在检测到这类裸字符串时会给出类型推断陷阱提示， 提醒用户注意跨解析器兼容性。

会。本工具基于 js-yaml v4，默认 schema 包含 timestamp 类型， 会把 YYYY-MM-DD 格式的值解析为 JavaScript Date 对象。 JSON.stringify 会把 Date 转为 ISO 8601 字符串： 2024-01-15 → "2024-01-15T00:00:00.000Z"（注意时区偏移）。 这会导致日期被转为带时区的 UTC 字符串，可能不是期望的结果。

# 会被解析为 Date 对象，转 JSON 后变成 ISO 8601 字符串
created: 2024-01-15
# → "2024-01-15T00:00:00.000Z"

# 保留为字符串，用引号包裹
created: "2024-01-15"

如果需要保留原始日期字符串，请用引号包裹。本工具在检测到日期格式的 裸字符串时会给出提示。

YAML 支持在一个文件中存放多个独立文档，用 ---（三个连字符）作为分隔符。 这是 YAML 独有的特性，JSON 不支持。常见用途：Kubernetes 多资源清单、Jekyll 多文章文件、 CI/CD 多阶段配置。例如：

---
name: doc1
value: 1
---
name: doc2
value: 2

本工具在检测到 --- 分隔符时会自动切换为多文档模式， 把每个文档解析后放入数组：转 JSON 后得到 [{ "name": "doc1", "value": 1 }, { "name": "doc2", "value": 2 }]。 输出区会显示「多文档 · N 个」标记。反向转换（JSON → YAML）不支持多文档， 因为 JSON 本身是单文档格式。

锚点和别名是 YAML 的引用复用机制，避免重复定义相同内容：

• 锚点 &id：给一个值起名字，后续可引用
• 别名 *id：引用之前定义的锚点
• 合并键 <<：把一个映射合并到当前映射（类似继承）

defaults: &defaults
  timeout: 30
  retries: 3
service_a:
  <<: *defaults
  name: a
service_b:
  <<: *defaults
  name: b

转 JSON 后，锚点和别名会被展开为完整结构（每个别名替换为锚点指向的内容）， 合并键会把父映射的字段合并进来。JSON 本身不支持引用复用，所以转换后会有数据重复， 但语义是等价的。本工具的 JSON → YAML 方向默认使用 noRefs: true， 不生成锚点 / 别名，确保输出 YAML 在所有工具中都能正确解析。

本工具的 JSON → YAML 转换采用仅在必要时加引号的策略（forceQuotes: false）， 大多数字符串不加引号以提高可读性。但以下情况必须加引号，否则会被 YAML 解析器误判：

• 看起来像数字的字符串："123" → "123"（不加引号会被解析为数字）
• 看起来像布尔的字符串："true" → "true"（不加引号会被解析为布尔）
• 看起来像 null 的字符串："null" → "null"
• 含特殊字符："a: b" → "a: b"（含冒号空格）
• 以特殊字符开头："- item" → "- item"（以 - 开头）
• 空字符串："" → ''

引号风格默认为双引号（"），与 JSON 保持一致。若字符串内含双引号， 会自动处理转义。这种「最小引号」策略既保证 YAML 可读性，又确保反向解析时类型不丢失。

这是 YAML 最常见的错误之一，通常是因为同一行出现了多个冒号，或冒号后没有空格。 YAML 规定键值对的冒号后必须有一个空格（除非值在下一行）。常见错误：

# 错误：冒号后没有空格
name:张三

# 错误：同一行多个冒号（value 中的冒号未加引号）
url: https://example.com:8080

# 正确
name: 张三
url: "https://example.com:8080"

本工具在解析失败时会给出精确的错误行号和列号，方便定位。 如果 URL 或值中含冒号，建议用引号包裹避免歧义。

本工具基于 js-yaml v4 库， 默认使用 YAML 1.2 core schema（与 PyYAML 等 YAML 1.1 解析器在布尔 / 日期处理上有差异）， 支持的常用特性：

• 支持：注释、多文档、锚点 / 别名、合并键、流样式（[1, 2] / {a: 1}）、 块样式、多行字符串（| 字面量 / > 折叠）、标签（!!str）
• YAML 1.2 与 1.1 差异：yes / no / on / off 在 1.2 中保留为字符串（本工具行为），在 1.1 中会被转为布尔；YYYY-MM-DD 在本工具中会被解析为 Date 对象 （js-yaml v4 默认 schema 含 timestamp 类型）。本工具检测到这类裸字符串会给出提示
• 不支持：自定义 schema、复杂数据类型转换

对于绝大多数配置文件（Kubernetes、Docker Compose、CI/CD、OpenAPI、GitHub Actions）， 本工具都能正确解析。如果遇到特殊语法导致解析失败，请检查 YAML 缩进与语法。