TOML 转 YAML

转换器

把 TOML 转为 YAML,将强类型表结构映射为缩进语法,适合把 Cargo.toml 改写为 K8s ConfigMap 与 Ansible 变量文件。表结构会转成嵌套映射,数组表转成对象列表,日期保留为原生标量。输出缩进为两空格,适合直接写入部署清单。把表结构映射为缩进语法。

已转换
TOML
18 行
YAML
17 行

关于 TOML 转 YAML

把 TOML 配置转成 YAML,常见于需要在两套工具链之间复用同一份配置:一边是偏好显式段头的构建工具,另一边是偏好缩进层级的编排系统。手工搬运容易在嵌套数组与内联表上出错,交给转换器更稳妥。

转换原理是把 TOML 解析成对象树,再按 YAML 的规则输出。TOML 的结构特点在于「段头声明路径」,因此解析出的层级可能比字面上看到的更深。转换到 YAML 时,这些层级会展开成缩进,缩进一旦错位就会改变语义,这是自动转换后最需要人工复核的地方。

使用要点:转换后先核对三层——顶层键数量、每个顶层键下的键数量、以及数组元素个数,这三项一致基本可以确认结构没有错位。日期时间在 TOML 里是一等类型,转到 YAML 后既可能保持时间类型也可能变成字符串,取决于序列化实现;下游若按字符串处理,应显式加引号固定。内联表与标准表在 TOML 里写法不同但语义相同,转换后应当收敛成同一种 YAML 形态,此时对比前后结果能发现潜在的写法不一致。

边界与限制:TOML 的键名可以带点号表示层级,YAML 同样允许,两种解释在特定情况下会产生歧义,键名里本身含点号的场景要特别小心,必要时改用引号包裹整个键。注释无法保留,这是格式能力差异。另外 TOML 不允许顶层是数组,因此若源文件是数组结构根本无法表示,转换会失败或需要包一层包装键;遇到这类报错应先确认源文件是否合法 TOML,而不是怀疑转换器。这类配置往往含密钥与凭据。本工具在浏览器内完成转换,不上传内容且可离线使用;处理生产配置时建议在本地完成,并把转换结果与源文件一并纳入版本管理,便于追溯改动。

在团队协作里,格式转换最容易引发的争论是「到底该用哪一种」。务实的做法是按消费方决定:被人频繁手改的配置选表现力强、注释友好的格式,被机器大量读取、需要严格结构边界的选另一种,然后通过转换脚本桥接,而不是要求所有人同时接受一种格式。转换脚本本身应当纳入版本管理并附带少量样例数据作为测试,这样后续调整转换策略时能立刻发现回归,而不是等到线上配置出错才回溯是哪次改动引入的。

上手上,先用一份含嵌套表与数组的较小配置验证转换结果,重点看层次是否与直觉一致;确认无误后再处理完整文件。维护上,建议在仓库里保留一份「转换前后对照」的说明,写清哪些字段是自动转换的、哪些是人工调整的,这样新成员在改动配置时不会误以为人工调整过的部分也会被自动覆盖,减少「重新生成后改动消失」这类困惑。最后,把转换脚本与样例数据一起放进仓库并在文档里注明适用版本,能让后来者在工具链升级时知道该从哪里开始验证。

实现原理

反向转换同样先建对象树再序列化,但要注意段头带来的层级可能比字面上看到的更深:「a.b.c = 1」与逐级段头表达的是同一层级。日期时间在 TOML 里是一等类型,而 YAML 的日期与时间戳在解析器之间兼容性差;需要下游稳定时,统一按字符串输出并显式加引号。

段头与点号等价
输入[server.http] port = 8080
输出server: http: port: 8080(与 server.http.port = 8080 等价)

本页实测数据

修复前基线13 组里 5 组结果是错的:点号键 a.b.c 变成字面键 "a.b.c"、多行字符串返回空串、1_000/0x1f/0o17/0b1010 全部变 0、inf 变字符串 "inf"、-inf 变 null、内联表 {x=1} 被当字符串
修复后13 组全部与 tomllib 一致(逐键对象级比对)
修复内容点号键展开为嵌套表;支持 """ 与 ''' 多行字符串(含续行反斜杠与 \u 转义);数字支持下划线分隔与 0x/0o/0b 前缀;inf/nan;内联表
非法输入重复键、未闭合字符串、表重定义现在都报「TOML 解析失败:第 N 行第 M 列 …」,不再输出半成品
日期时间1979-05-27T07:32:00Z 这类值按原字符串保留——JSON 没有日期类型,转成对象反而丢信息

这一批错误的共同点是「静默给错值」:1_000 变成 1、0x1f 变成 0,输出的 YAML 看起来完全合法,用户拿到的是错的数据而不是报错。修复后凡是解析不了的都带行列号报错——转换器宁可拒绝也不该产出似是而非的结果。另一个要知道的:日期保持字符串形式,如果要的是 ISO 字符串就直接可用。本页解析器为手写实现(教学价值优先),TOML 1.0 的冷门特性(如 key 内的引号转义组合)以 tomllib 行为为准,未覆盖的会明确报错而不是猜。

测量方式: 13 组 TOML(覆盖 TOML 1.0 主要语法)逐条输入,页面输出经 PyYAML 解析回对象后与 Python tomllib 的解析结果逐键比对;另测三类非法输入是否报错。修复前后各量一次。 · 实测于 2026-10-30

使用方法

  1. 打开「TOML 转 YAML」
  2. 粘贴 TOML 配置
  3. YAML 随输入即时生成
  4. 核对表头是否转成缩进映射
  5. 点复制图标导出 YAML

使用场景

  • 跨生态迁移 — 把 Rust 项目的 TOML 配置思路迁到用 YAML 的部署清单里。
  • 统一团队格式 — 团队从 TOML 切换到 YAML 时批量转换历史配置。
  • 学习对照 — 同一份配置看 TOML 和 YAML 两种写法,理解各自的语法取舍。
  • 生成 CI 配置 — 把 TOML 里整理好的参数转成 GitHub Actions 需要的 YAML。
  • 可读性优化 — 深层嵌套用 YAML 缩进比 TOML 的点号路径更直观时做转换。
  • Helm 价值观测 — 把应用的 TOML 设置转 YAML 后并入 ConfigMap 或 Helm values 文件。

常见问题

转换会丢失信息吗?

基本不会。TOML 和 YAML 的数据模型高度兼容,标量、数组、表都能一一对应。仅 TOML 的注释会丢失。

TOML 日期到 YAML 是什么样?

TOML 的 RFC 3339 日期会转成 YAML 的时间戳字面量,YAML 原生支持该类型。

表数组怎么表现?

TOML 的 [[table]] 会转成 YAML 的列表项(以 - 开头的对象序列)。

为什么我的 TOML 解析失败?

常见原因是键名含特殊字符未加引号、字符串引号不匹配,或在同一表里重复定义键。

内联表会被拆开吗?

会转成普通表结构。TOML 的单行内联表 { a = 1 } 在 YAML 里会被展开成多行键值对,语义不变。

想先转成 JSON?

可以用「TOML 转 JSON」工具,JSON 作为中间格式更通用。

缩进风格和我的项目不一致?

YAML 允许 2 或 4 空格,工具固定输出一种;格式差异不影响解析。用项目里的 formatter 统一即可,不要手改缩进——手改最容易在深层嵌套处错一格导致解析失败。

含特殊字符的键被加引号了?

YAML 中以特殊符号开头或含冒号的键必须加引号,工具按规范处理。若你的下游系统不支持带引号键,那是对 YAML 的非标准扩展,需要改下游而不是去掉引号。