TOML 格式化 + 互转:TOML 1.0, ↔ JSON, ↔ YAML, 带行列号错误

真实使用场景

• 提交前把乱掉的 `Cargo.toml` 整理回标准形态

  调试时加了三个依赖, 现在 `Cargo.toml` 里 2 空格和 4 空格混 用, 还有一行 `features = ["serde", "tokio", "reqwest", "rustls"]` 拉到 95 列。粘进来, 点 "格式化 TOML", 勾上 "键按 A→Z 排序" 让 `[dependencies]` 按字典序排好 (CI lint 要的), 复制回去。 现在跟 main 的 diff 只剩你新增的三个依赖, 不再混着 40 行 空白格式抖动。

• 从 `pyproject.toml` 抽配置给一个 Python 脚本读

  写一个脚本要读 `[project] name`、`version`、`dependencies`, 其他工具链都说 JSON。粘 `pyproject.toml`, 切换 "TOML → JSON", 复制。现在 `meta = json.loads(open(...).read())` 拿到的形状 和 `[project]` 完全一致, 不用引 `tomllib`, 也不用纠结 Python 3.11 标准库的细节。

• 把 YAML 的 CI 配置移植到 Rust 工具的 TOML

  有一个 `.github/workflows/build.yml`, 想把里面的 job matrix 搬到 Cargo 旁边的 `xtask/config.toml` 里。粘 YAML 块, 切到 "YAML → TOML", 复制。输出里每个 job 是一个 `[[matrix]]` 表 数组元素, `xtask` 二进制用 `toml::from_str` 读。同一份矩 阵, 同一份事实来源, 两个格式。

• 排查 build 报 "TOML parse error" 但没给上下文的 `netlify.toml`

  Netlify 的 build 报错只有 "TOML parse error at line ?? col ??" 一句, 没上下文。粘 `netlify.toml`, 这里给精确行号、列号, 加 3 行上下文, 出错字符下方有 `^`。多半是某个值没加引号 (`status = 301 force` 写法不对, 应该是 `force = true` 单 独一行) 或者 `[[redirects]]` 头少了 `]`。5 秒修完, 推上去。

• 多环境数据库配置在 staging 和 prod 之间对齐

  一个 `db.toml` 里有 `[default]`、`[development]`、`[staging]`、 `[production]` 四个块。想确认 staging 和 production 之间只 有 `host` 和 `pool_size` 不一样。把两段都用 "键按 A→Z 排序" 格式化, 用 `git diff --no-index` 对比, 你只会看到这两处刻 意的差异。没人趁夜里偷偷改过别的字段。

• 从 JSON 模板生成 Discord / Telegram 机器人配置块

  原型阶段用的是 JSON 形状的机器人配置, 但目标运行时 (Rust serenity、Python aiogram 配 TOML 扩展) 要 TOML。粘 JSON, 切 "JSON → TOML", 复制到 `config.toml`。`[[commands]]` 那一段 object 数组会变成 `[[commands]]` 表数组。框架的 `serde` 派生期望的就是这个形状。

常见踩坑

• 把 `.env` 当 TOML 粘进来然后失败。`.env` 允许 `KEY=value` 不加引号; TOML 要求带空格或特殊字符的字符串必须加引号。把每个值用引号包一下 (`KEY="value"`) 就能解析。

• 期待 `inf` / `nan` 在 TOML 转 JSON 时保留。JSON 规范禁止这两个值, 所以我们会平铺成 `null`, FAQ 里有说明。如果你的值真的是 `nan`, 几乎肯定是算法 bug, 该在源头修, 不是序列化的问题。

• 想格式化后保留注释。解析器刻意不保留注释, 因为加上这个功能解析器要翻 3 倍, 而绝大多数工作流用不上 (Prettier 的 TOML 模式也是这个取舍)。要看真正改动用 git diff。

• 把点号键当成 JSON 里的层级嵌套理解错。TOML 里 `a.b.c = 1` 和 `[a.b] c = 1` 完全一样。JSON 输出都是 `{a: {b: {c: 1}}}`。没有 "扁平带点号" 的 JSON 中间形式。

• 粘根是数组的 JSON 期望出 TOML。TOML 要求根是表 (object)。把数组先包成 `{ "items": [...] }`, 转换器会输出 `[[items]]` 表数组。

• 期待键排序把数组元素也排了。键排序只排表的 KEY。`[[products]]` 表数组的元素和 `[1, 3, 2]` 标量数组的元素都保持源顺序, 因为 TOML 语义上数组顺序是数据。

隐私说明