TOML 格式化与校验完全指南:看懂 Cargo.toml 与 pyproject.toml

写 Rust 的人离不开 Cargo.toml,写现代 Python 的人离不开 pyproject.toml。这两个文件的格式都是 TOML。很多人天天改它,却没真正搞清楚它的表语法和缩进规则,改完一提交,diff 里全是空白抖动,review 的人想骂街。这篇把 TOML 是什么、表 table 怎么读、怎么格式化校验、怎么和 JSON YAML 互转,一次讲透。

TOML 是什么,为什么配置文件偏爱它

TOML 的全称是 Tom's Obvious, Minimal Language,目标只有一个:让配置文件一眼就能读懂。它比 JSON 多了注释,比 YAML 少了缩进歧义。YAML 一个空格错位整个文件含义就变了,TOML 用显式的方括号分节,不靠缩进表达层级,所以不会因为 Tab 和空格混用而炸。

它在工具链里的位置很稳:Rust 的 Cargo.toml、Python 的 pyproject.toml、Hugo 的 config.toml、Netlify 的 netlify.toml,都默认用 TOML。你只要长期碰这几个生态,就一定要会读它。

表 [table] 语法:键值对到底怎么分节

TOML 的核心就是表。一个 [section] 开一个分节,下面的键值对都属于这个节。这是它最该被讲清楚的一个点。

[package]
name = "my-crate"
version = "0.3.0"

[dependencies]
serde = "1.0"
tokio = { version = "1", features = ["full"] }

[package] 下的 name 和 version 属于 package 表,[dependencies] 下的 serde、tokio 属于 dependencies 表。还有一个进阶语法叫表数组,用双方括号 [[products]]:每写一次 [[products]] 就追加一个数组元素,这正是 Cargo 里 [[bin]]、[[example]] 的写法。点号键 a.b.c = 1 等价于 [a.b] 里写 c = 1,转成 JSON 都是 {a: {b: {c: 1}}},没有第三种扁平形式。

格式化与校验:让 diff 只剩真实改动

配置文件最烦的不是写错,是格式不统一。调试时加了三个依赖,顺手把一段缩进从 2 空格敲成了 4 空格,还有一行 features 拖到了 95 列。提交后跟 main 的 diff 里,真实改动只有三行,却混进 40 行空白抖动。

TOML 格式化 + 互转 解决的就是这件事。粘进来,选 2 空格、4 空格或 Tab 缩进,数组样式可以强制单行或多行,再勾上键按 A→Z 排序,[dependencies] 就按字典序排好。很多团队在 CI 里强制字典序就是为了 diff 稳定。校验这块也实在:语法错了会给出精确行号、列号,加 3 行上下文,出错字符下方还有一个 ^ 标记,跟编译器一样准。

下面是格式化前后的真实对比。格式化前:

[dependencies]
   tokio="1"
serde = "1.0"
   reqwest = "0.11"

格式化后(2 空格缩进 + 键排序):

[dependencies]
reqwest = "0.11"
serde = "1.0"
tokio = "1"

缩进对齐了,键也按字母排好了,再有人改动一眼就看得出动了哪行。

和 JSON YAML 三向互转的实操

我自己最常用的不是格式化,是转换。写脚本要读 pyproject.toml 里的 [project] 元数据,而手头工具链全说 JSON,这时候切到 TOML → JSON,复制出来直接 json.loads,不用引 tomllib 也不用纠结标准库版本差异。反过来,把一段 YAML 的 CI job matrix 移植到 Rust 工具的 config.toml,切 YAML → TOML 就行,输出里每个 job 自动变成 [[matrix]] 表数组元素。

互转有两个坑要记住:TOML 转 JSON 时,日期时间会变成 RFC 3339 字符串,因为 JSON 没有 datetime 类型;inf 和 nan 会变成 null,因为 JSON 规范不允许。JSON 转 TOML 时,根必须是 object,数组根没有 TOML 对应形式,得先包成 { "items": [...] }。如果你经常在 YAML 和 JSON 之间来回,也可以配合 YAML 格式化工具 一起用,两边对齐了再做最后一步互转。

几个最容易踩的坑

第一,别把 .env 当 TOML 粘。.env 是 KEY=value 不加引号,TOML 要求带空格或特殊字符的字符串必须加引号,把每个值用引号包一下就能解析。第二,别指望格式化保留注释,主流 TOML 格式化器普遍不保留,要看真实改动请用 git diff。第三,键排序只排表里的键,不会重排 [[products]] 元素或 [1, 3, 2] 的顺序,因为 TOML 语义上数组顺序是数据,不是排版。把这三条记牢,TOML 基本不会再坑到你。

---

Made by Toolora · Updated 2026-06-13