格式化

YAML 格式化

YAML 代码格式化、验证和转 JSON

YAML 输入
结果

YAML 格式化工具

YAML (YAML Ain't Markup Language) 是一种人类可读的数据序列化标准,常用于配置文件、数据交换等场景。

功能特点

  • 格式化:美化 YAML 代码,统一缩进和格式
  • 验证:检查 YAML 语法是否正确
  • 转 JSON:将 YAML 转换为 JSON 格式
  • 自定义缩进:支持设置缩进大小(1-8 空格)

使用场景

  • 配置文件:格式化 Docker Compose、Kubernetes 等配置文件
  • CI/CD:格式化 GitHub Actions、GitLab CI 等配置文件
  • 数据交换:在不同系统间转换数据格式
  • 代码审查:统一团队代码格式

粘贴 YAML 后,本工具用 js-yaml 4 解析并重新序列化:统一缩进、把行内集合展开成块集合、报出首个语法错误的行列,或整篇转成 JSON。排查 Docker Compose、K8s 清单里混进的 Tab、忘了加引号的版本号时最直接。

格式化是「解析再写回」,不是重排文本

组件不改动你的字符,而是把输入交给 js-yaml 4.1.1 解析成 JavaScript 值,再把值写回去。类型在解析阶段就已确定:YAML 1.2 core schema 下只有 true 与 false(含首字母大写形式)算布尔,yes、no、on、off 一律是字符串,这与仍按 1.1 规则解析的库行为不同。裸写的 1.20 会变成数字 1.2,版本号必须加引号;未加引号的 2024-01-01 被识别为日期对象,回写时变成 2024-01-01T00:00:00.000Z。超过 9007199254740991 的整数以双精度浮点存放,末尾几位会被悄悄改掉。

注释、锚点、引号风格为什么都留不下来

中间产物只有「值」,没有承载这些信息的位置。注释直接消失;写回时传了 noRefs: true,锚点被就地展开,一个映射被引用两次就会完整输出两遍;合并键 << 在解析阶段已经合并完毕。lineWidth: -1 关掉了默认的 80 列折行,长字符串因此保持单行。需要引号时一律写双引号,不会出现单引号。indent 决定每层缩进的空格数,块序列项也跟着缩进,缩进为 2 时短横线落在键右侧两个空格处。字符串键按插入顺序输出,所以键序与原文一致。

一次只吃一个文档,以及报错怎么读

组件调用的是 yaml.load 而非 loadAll,输入里出现第二个 --- 分隔符就会失败,提示 expected a single document in the stream, but found more,Kubernetes 那种多文档清单得先拆开。报错位置是 1 起始的行:列,例如 tab characters must not be used in indentation (2:1),指向第一个出问题的字符,而不是看起来可疑的上一行。同一映射内重复的键直接报错,不会让后一个覆盖前一个。自定义标签没有注册进 schema,!Ref 会得到 unknown tag 报错,因此 CloudFormation、Serverless 模板在这里根本无法校验。

实操示例

把行内序列与 4 空格子映射规范成 2 空格

输入
app: "DevToolbox"
release: "1.20"
ports: [8080, 8443]
env:
    DEBUG: false
输出
app: DevToolbox
release: "1.20"
ports:
  - 8080
  - 8443
env:
  DEBUG: false

1.20 的引号必须保留,去掉后重新解析就变成数字 1.2;DevToolbox 的引号反而被丢掉,因为没有哪种标量类型会认领它。行内序列被展开成块序列、4 空格子映射被改成 2 空格,这两处都是写回时的默认行为,与你原本的排版无关。把输出再解析一遍,得到的对象与输入完全一致。

边界与常见误用

  • 格式化模式缩进取 1–8 个空格,转 JSON 模式取 0–8;填 0 时 JSON 压成单行,因为 JSON.stringify 把缩进 0 当作不美化。
  • 解析再写回意味着注释、锚点、合并键以及你原本的引号风格和行内/块写法都不会保留,拿输出跟原文 diff 只会看到排版噪音。
  • 输入只允许一个文档,含第二个 --- 的文件必须先拆分再粘贴,多文档 K8s 清单常踩这一条。
  • !Ref、!Sub 这类自定义标签没注册进内置 schema,会被判为未知标签,CloudFormation / Serverless 模板无法校验。
  • 转 JSON 时无引号时间戳会变成带毫秒的 ISO 字符串,超过 9007199254740991 的整数会被取整,两者都不是原样输出。

相关工具

什么时候用这个页面,什么时候该换工具

你手上的活这个页面该换条路的情况
手动排查一个清单文件格式化模式把粘贴内容交给 js-yaml 4 解析再写回,缩进可填 1–8 个空格,结果面板是只读文本,复制带走即可。内容不出浏览器,磁盘上的文件不会被改动。yq -P -i 直接改写文件本身,一次一个路径,一个目录的清单写成 shell 循环比粘贴四十次快。改动需要落进仓库、而不是落在剪贴板时,就走这条。
整理一个 .json 文件JSON 是 YAML 的子集,所以把 {"a":1} 粘进格式化模式不会报错,输出会变成块状 YAML,即 a: 1——这是格式转换,被当成了格式化。JSON 格式化工具的输出仍能被 JSON.parse 读取,缩进固定为 2 空格、4 空格或 1 空格三档,另有压缩面板并能生成 TypeScript 接口。下游代码要按 JSON 解析时用它。
要一份压成一行的 JSON转 JSON 模式走 JSON.stringify,缩进可取 0–8;填 0 整篇压成一行,这是本页唯一的压缩能力。JSON 已经存在、只差压缩或换个缩进时,JSON 格式化工具有独立的压缩面板和固定三档缩进,还能顺带生成 TypeScript。
能解析,但内容依然是错的校验模式只报解析器拒收的东西:缩进错、重复键、未知标签。少了 apiVersion 的 Deployment,或者 image: "",在这里都算通过。风格与行宽用 yamllint,K8s 字段校验用 kubeconform 或 kubectl apply --dry-run=client,满是 !Ref 的模板用 cfn-lint。先让本页说通过,再跑这些——它把的是语法关,不是 schema 关。
两百个文件,或者一次超长粘贴文本框每敲一个键都会同步跑一遍解析加写回,没有防抖也没有 Web Worker,长篇内容在输入过程中就被反复重新解析。用 js-yaml 写个 Node 脚本,或者在 CI 里调 yq,同类工作可以无人值守地批量跑完。活一旦变成重复劳动,就该换过去。

一个具体场景

先把模式值加引号,再点格式化

一份清单里写着 fsGroup: 0o755,三个挂载文件共用 defaultMode: 0644,还有一行把三个挂载写成了行内列表。格式化模式会把两个模式值当数字解析,输出变成 493 和 644,两次都是十进制,结果里没有任何标记提示原本是八进制。那行行内列表也经历同样的事:原本 1 行装 3 个元素,回来是 4 行,于是一个字都没改、只点了一次格式化,输出反而比输入更长。把它们写成 "0o755"、"0644" 再格式化,值才会以字符串形态穿过写回。凡是前导零或进制本身有意义、事后无法反推的配置值,都该先加引号。

常见问题

YAML 为什么总报"缩进错误"?
YAML 用缩进表达层级,且比 Python 更严格:只能用空格不能用 Tab、同级元素必须对齐。排查技巧:把可疑区域粘贴进来校验,工具会指出第一个出错行;90% 的问题是 Tab 混入或多打了一格。
值什么时候必须加引号?
含特殊字符就必须加:以 * & { } [ ] , # | > ! % @ ` 开头的值、含 ": " 的值、前导/尾随空格,以及看起来像数字或布尔的字面量。经典坑:版本号 1.20 不加引号会变成数字 1.2,国家码 NO 会变成布尔 false。
YAML 和 JSON 可以互转吗?
可以,YAML 1.2 是 JSON 的超集。CI 配置(GitHub Actions)、K8s 清单经常需要互转;注意转换后注释会丢失——YAML 的注释在 JSON 里没有对应物。

内容复核: