关于 JSON 转 TOML
JSON 转 TOML 工具把 JSON 数据换成 TOML 写法,直接用于 Cargo、Poetry 或 Go 项目的配置文件。TOML 有段头、支持注释,人读起来比一层层括号清楚,日期时间还是一等类型,可以直接写带时区的时刻;JSON 仍是接口与前端最通用的交换格式。工具会处理嵌套对象、数组和基本类型,遇到 TOML 表达不了的结构会给出提示,结果实时显示并可一键复制;评审配置变更时,段头也让「这一项属于哪个模块」一眼可见。
两个边界先知道。一是 TOML 没有 null,值为 null 的键会被跳过、从结果里消失,跨工具消费时要先约定用空字符串还是干脆省略。二是嵌套超过三四层后,段头会堆得很长,可读性反而不如 JSON,这种配置该考虑拆分而不是硬转。
转换原理是解析成对象树再按 TOML 规则输出:顶层对象变键值对,嵌套对象变段头,数组按元素类型决定用单方括号还是双方括号。这里最容易出错的就是数组——对象数组必须用双方括号,判断错了会产出解析不了的文件。所以转完别只看文本像不像,用解析器再读一遍确认能解析。
使用时先把「看着像数字或布尔、其实是标识」的字段加引号固定成字符串:版本号、以零开头的编号、取值恰好是 on/off 的枚举,否则往返一次类型就变了。转完核对键的总数和嵌套深度,确认没有内容因为同名段头被合并掉——TOML 里同名段头是追加而不是覆盖,和直觉相反。
注释迁不过来,说明性文字得写进字段值或另存文档;JSON 允许顶层是数组而 TOML 不允许,数组型配置要先包一层键。配置里通常有连接串和密钥,工具在浏览器内完成转换、不上传内容、可离线使用;迁移生产配置建议先用脱敏样本跑通流程。
实现原理
TOML 没有 null,也没有「顶层数组」这种写法,这两个限制是转换时最先要处理的。同名段头在 TOML 里是追加而不是覆盖,所以两个同名的对象会被合并成一段,键相同时后一个生效——这不是 bug,是格式规则。
{"a":{"b":1},"list":[{"x":1}]}[a]
b = 1
[[list]]
x = 1(嵌套成为段头,对象数组用双方括号)本页实测数据
| 修复:null 被写成空串 | TOML 没有 null,旧实现输出 n = "" ——「缺失」被静默改写成「空字符串」。现在跳过该键(a = 1 保留、n 不出现) |
|---|---|
| 修复:含点号的键被当路径 | {"a.b":1} 输出 "a.b" = 1 而不是 a.b = 1——后者在 TOML 里是「表 a 的键 b」,结构完全变了 |
| 修复:大整数丢末位 | 9007199254740993 输出为带引号的 "9007199254740993",不再变成 …992 |
| 对象数组 | {"t":[{"x":1},{"x":2}]} 输出两个 [[t]] 表,顺序与源一致 |
把 JSON 落到 TOML 有三处结构性落差,本页实测覆盖了全部:①没有 null——只能省略键,若下游依赖「键存在但值为空」,得自己替换成空串或占位值;②键的引号语义不同——TOML 里 a.b = 1 表示表 a 下的键 b,带点号的字面键必须写成 "a.b";③数字精度——JSON 数字走双精度,超 2^53 的整数只能以字符串表达,输出会带引号。另一个方向(TOML→JSON)也有类似落差,但 JSON 能表达 null,所以宽松一些。
使用方法
- 打开「JSON 转 TOML」
- 粘贴 JSON,嵌套对象会成表
- 右侧 TOML 随输入即时刷新
- 核对表头与数组的写法
- 点复制图标把 TOML 送入剪贴板
使用场景
- 生成 Cargo 配置 — 把 JSON 描述的依赖列表转成 Cargo.toml 中的 [dependencies] 段落。
- 迁移 Python 项目 — 将 setup.py 中的 JSON 化元数据转成 pyproject.toml 所需的 TOML 结构。
- 配置格式统一 — 团队约定用 TOML 时,把历史的 JSON 配置批量转换过来。
- 理解 TOML 表结构 — 通过 JSON↔TOML 对照,直观看懂嵌套表和表数组的写法。
- 工具链对接 — 把 API 返回的 JSON 转 TOML 后供 Hugo、Netlify 等读取。
常见问题
JSON 的 null 怎么转?
TOML 规范没有 null 类型。本工具会跳过值为 null 的键,因为 TOML 无法表示空值,请注意转换后这些键会消失。
嵌套数组对象会变成什么?
对象数组会转成 TOML 的「表数组」语法 [[table]],这是 TOML 表达重复结构的标准方式。
深层嵌套支持吗?
支持,但 TOML 对极深嵌套的可读性不如 JSON。如果嵌套超过 3-4 层,建议考虑是否拆分配置。
日期时间如何处理?
JSON 里日期通常是字符串,转 TOML 后仍是字符串。TOML 原生支持的日期类型需要符合 RFC 3339 才会被识别。
键的顺序会变吗?
不会,转换保持插入顺序,方便你逐段对照原始 JSON 与结果是否一一对应。
想反向转换?
请使用本站的「TOML 转 JSON」工具。
转换后嵌套数组的结构变了?
TOML 对「对象数组」必须写成 [[array]] 段落形式,与 JSON 的嵌套写法不同;嵌套数组里的对象会展开成独立的段。结构语义等价,但视觉上差别大。解析回去是等价的,不是数据丢失。
键名里有空格或特殊字符怎么办?
TOML 允许带引号的键,工具会自动加引号;含点号的键会被转成嵌套表,这可能改变层级。如果键名本身含点且你希望保持平铺,需要手动给整段键加引号,否则会被解析成嵌套。