YAML 格式化完全指南：缩进、多文档与 JSON 互转

1. YAML 在工程里到底管什么

YAML（YAML Ain't Markup Language）是面向人的数据序列化语言，广泛出现在：

• 容器与编排：docker-compose.yml、Kubernetes Deployment / Service
• CI/CD：GitHub Actions、GitLab CI、部分 Jenkins 配置
• 应用配置：Spring 的 application.yml、Ansible playbook、Helm values
• 内容与元数据：部分静态站点 frontmatter、OpenAPI 的 YAML 形态

它的卖点是 可读：少括号、可注释、层级靠缩进。代价是 对空白极度敏感，且同一段文本在不同解析器（PyYAML、js-yaml、Go yaml.v3、SnakeYAML）上对「重复键、锚点、类型猜测」的行为不完全一致。

本站工具基于浏览器内的 js-yaml：输入框粘贴后可实时校验；「美化 YAML」用 dump 以 2 空格重写；「压缩」走 flow 风格；并支持 YAML↔JSON。处理在本地完成，粘贴含密钥的配置前仍应脱敏。

2. 缩进、标量与列表：必须刻进肌肉记忆的规则

只用空格，不要用 Tab

YAML 1.1/1.2 实践中，缩进应使用空格。编辑器若把 Tab 显示成「看起来对齐」，解析器仍可能报错或层级错乱。团队应统一 2 空格（K8s/GitHub Actions 常见）或 4 空格，并在编辑器开启「以空格代替 Tab」。

同级对齐，子级多缩进一级

# 合法：同级键左缘对齐，子键多 2 空格
server:
  host: localhost
  port: 8080
  ssl:
    enabled: true

下面是故意非法的示例（子键比父键还靠左，或同级不对齐）：

# 故意非法
server:
host: localhost
  port: 8080

列表项的 - 位置

- 后一般有一个空格；列表项下的嵌套映射要与内容列对齐：

containers:
  - name: web
    image: nginx:1.25
  - name: sidecar
    image: busybox

字符串何时必须加引号

# 危险：某些解析器会把 yes 当成 true
feature_flag: yes

# 更稳妥
feature_flag: "yes"
version: "1.10"
message: "error: not found"

多文档与文档头

--- 分隔多个文档；... 可结束文档（较少手写）。K8s 里一份清单常含多个资源，用多文档拼在一个文件里。

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: v1
kind: Secret
metadata:
  name: app-secret

工具边界： 页面校验使用 jsyaml.load，对多文档字符串可能只解析第一段或直接报错，取决于输入形态。多文档清单建议：分段粘贴校验，或先确认你的目标运行时（kubectl）如何加载；不要假设「网页一次 load = kubectl apply 全部文档」。

3. YAML 与 JSON：差异与有损点

两者常互转，但不是信息论上的完全等价。

何时留在 YAML： 给人读的配置、需要注释与锚点复用、编排与 CI 清单。 何时转 JSON： 接口调试、前端 JSON.parse、需要与 JSON 格式化 / Diff 工具链对接。 专用转换页： 若你的主任务就是反复 JSON↔YAML 且不强调「YAML 美化风格」，可用 JSON ↔ YAML；本篇主工具把校验 + 美化 + 压缩 + 互转放在同一屏，适合排错时少开标签页。

前后对照：同一结构两种写法

YAML：

user:
  id: 1001
  name: Ada
  roles:
    - admin
    - editor
  active: true

等价 JSON：

{
  "user": {
    "id": 1001,
    "name": "Ada",
    "roles": ["admin", "editor"],
    "active": true
  }
}

把 YAML 里的 active: yes 转成 JSON 后，可能变成 true 而不是字符串 "yes"——这是类型猜测，不是格式化「弄坏了字段名」。

4. 用 WebUtils 处理 YAML：逐步操作

工具页：YAML 格式化。

1. 打开页面。 进入 /tools/dev/yaml-formatter，左侧为「输入 YAML / JSON」，右侧为「处理结果」。
2. 粘贴内容。 可点「加载示例」熟悉布局；真实配置请先去掉密码、Token、私钥。
3. 看状态栏。 输入时会 oninput 触发校验：成功显示「YAML 格式正确」；失败显示 js-yaml 的错误信息（含行/列线索时优先按行改缩进）。
4. 美化。 点「美化 YAML」：在能 load 的前提下，用 2 空格 dump 到右侧（lineWidth: -1、noRefs: true，避免锚点引用写法干扰阅读）。
5. 压缩。 点「压缩 YAML」：以 flow 风格尽量收紧空白，便于对比「解析后结构」而非阅读。
6. 转 JSON。 「YAML 转 JSON」输出缩进后的 JSON；再可用 JSON 格式化 做二次整理或压缩。
7. JSON 转 YAML。 左侧若是 JSON，点「JSON 转 YAML」；非法 JSON 会在状态栏报 JSON.parse 错误。
8. 复制与清空。 输入/结果区均可「复制」；「清空」同时清两侧与状态。

能力边界（对照真实页面）

• 支持： 语法校验、美化 dump、flow 压缩、YAML→JSON、JSON→YAML、示例与主题切换。
• 不保证： 保留原注释与原手写风格；多文档一次性完整 round-trip；所有 YAML 1.1 怪异类型在全语言生态一致。
• 安全： 浏览器本地解析；仍不要在不可信环境粘贴生产 Secret 明文。

5. 常见错误与处理办法

建议排错顺序

1. 是否混用 Tab / 全角空白。
2. 报错行附近 :、-、引号是否成对。
3. 类型猜测是否把字符串吃成布尔/数字。
4. 是否多文档只检查了一段。
5. 最后才怀疑业务字段名写错。

6. 真实工作场景

场景 A：kubectl apply 被拒，怀疑是缩进

从失败清单中复制相关片段（脱敏），贴进工具。若状态栏直接报错，按行号改；若校验通过，再怀疑 API 版本、必填字段或 RBAC——格式化工具只证明「这是合法 YAML 对象树」，不证明「集群接受该资源」。

场景 B：GitHub Actions 在 with: 下莫名其妙

run: 多行脚本、with: 下的 : 字符串最容易炸。把 job 片段贴入工具校验；对含冒号的消息使用引号或块标量（| / >）。美化后把片段贴回 workflow 文件，避免在网页里改完整仓库密钥。

场景 C：后端给 JSON，运维要 YAML values

左侧贴接口样例 JSON →「JSON 转 YAML」→ 复制到 Helm values 草稿。再人工补注释与环境差异。若 JSON 很大，先在 JSON 格式化 确认合法并压缩字段认知负担。

场景 D：Code Review 里「同逻辑、不同风格」

双方各贴一份 YAML，都美化成 2 空格后再 diff（编辑器或专用 diff）。减少「空格战争」对逻辑审查的干扰。注意：美化会丢注释，review 注释需看原文件。

场景 E：怀疑类型导致的配置「偶发」

同一份配置在 Node 与 Python 服务行为不同。转成 JSON 后看每个叶子的 JSON 类型；对版本号、国家代码、以 0 开头的编号统一加引号，从源头消除猜测。

场景 F：教学「为什么不能从聊天软件直接拷配置」

演示：从富文本拷贝导致的奇怪空白 → 校验失败；纯文本或「加载示例」→ 成功。让新人建立「配置只走代码库与纯文本」的习惯。

8. 相关工具怎么选

选型口诀：YAML 报错先格式化页校验；只做 JSON/YAML 桥接可用转换器；进 JSON 生态后用 JSON 工具链。

常见问题

继续浏览

先用「加载示例」走通「粘贴 → 看状态栏 → 美化 → 转 JSON」，再拿真实脱敏片段对照错误表。需要纯 JSON 排错时打开 JSON 格式化；需要桥接转换时打开 JSON↔YAML。