参考：TOML 语法速查
基于 TOML 1.0.0 · 核于 2026-07
速查
- 定位：Tom's Obvious Minimal Language，面向人类的配置格式；无歧义映射哈希表；1.0.0（2021-01）为事实标准。
- 顶层要素：键值对
键 = 值、注释#、表[t]、表数组[[t]]。 - 键：裸键
A-Za-z0-9_-／ 引号键"..."'...'／ 点分键a.b.c。 - 字符串四型：
"基本"（转义）／"""多行基本"""（首换行删、行尾\续行）／'字面'（不转义）／'''多行字面'''。 - 数字：整数 64 位有符号（
0x/0o/0b、下划线、禁前导零）；浮点 IEEE 754（inf/nan小写、小数点两侧须有数字）。 - 布尔：
true/false（小写）。 - 日期时间：带偏移 / 本地日期时间 / 本地日期 / 本地时间（RFC 3339）。
- 复合：数组
[ ]（可混合类型、可尾随逗号）／内联表{ }（自包含、禁尾随逗号、单行）／表数组[[t]]（追加元素）。 - 不可：重复定义键/表、点分键后重定义该表、键值与表类型冲突、静态数组被
[[ ]]追加。 - 官方：toml.io ｜ v1.0.0 规范 ｜ toml-lang/toml。
一、类型速查表
| 类型 | 写法示例 | 要点 |
|---|---|---|
| 基本字符串 | "hello\n" | 双引号，支持 \n \t \" \\ \uXXXX \UXXXXXXXX |
| 多行基本字符串 | """...""" | 跨行；首换行删除；行尾 \ 续行不留换行 |
| 字面字符串 | 'C:\path' | 单引号，不转义，单行 |
| 多行字面字符串 | '''...''' | 不转义、跨行；内部最多连续 2 个单引号 |
| 整数 | 42 -17 1_000 0xFF 0o755 0b101 | 64 位有符号；禁前导零；进制形式禁 +/- |
| 浮点 | 3.14 5e+22 inf nan | IEEE 754；小数点两侧须有数字；特殊值小写 |
| 布尔 | true false | 只小写 |
| 带偏移日期时间 | 1979-05-27T07:32:00Z | RFC 3339，绝对时刻 |
| 本地日期时间 | 1979-05-27T07:32:00 | 无时区 |
| 本地日期 | 1979-05-27 | 仅日期 |
| 本地时间 | 07:32:00 | 仅时间 |
| 数组 | [1, "a", true] | 有序、可混合类型、可尾随逗号 |
| 内联表 | { x = 1, y = 2 } | 单行、自包含、禁尾随逗号 |
| 表 | [server] | 声明一张表 |
| 表数组 | [[products]] | 每次追加一个表元素 |
二、键的三形态
| 形态 | 示例 | 允许字符 |
|---|---|---|
| 裸键 | bare_key 1234 | ASCII 字母/数字/_/- |
| 引号键 | "127.0.0.1" 'key' | 任意（走字符串规则） |
| 点分键 | a.b.c = 1 | 各段按键规则，点号分层 |
三、合法 / 非法对照
| 场景 | 合法 | 非法 |
|---|---|---|
| 浮点小数点 | 0.5 5.0 | .5 5. 3.e+20 |
| 整数前导零 | 0 0o123 | 0123 007 |
| 特殊浮点 | inf nan | Inf NaN Infinity |
| 布尔 | true false | True yes on 1 |
| 数组尾随逗号 | [1, 2,] | —（数组允许） |
| 内联表尾随逗号 | { a = 1 } | { a = 1, } |
| 键重复 | 各定义一次 | a = 1 两次 / x 与 "x" 同名 |
| 点分键后表头 | 追加新子表 [a.b.c] | 重定义 [a.b] |
| 静态数组 vs 表数组 | 一开始就 [[x]] | x = [] 后 [[x]] |
四、生态落地一览
| 项目 / 工具 | 文件 | 用途 |
|---|---|---|
| Rust Cargo | Cargo.toml | 包清单：[package]/[dependencies]/[[bin]] |
| Python 打包 | pyproject.toml | [build-system](PEP 518) + [project](PEP 621) |
| Ruff / Black / mypy | pyproject.toml | [tool.*] 命名空间下的工具配置 |
| Cloudflare Wrangler | wrangler.toml | Workers 部署配置 |
| Netlify | netlify.toml | [build]/[[redirects]]/[[headers]] |
| Hugo | hugo.toml | 站点配置（旧名 config.toml） |
| Taplo / Tombi | — | 格式化 + LSP |
| Python 3.11+ | — | 内置只读解析库 tomllib |
五、TOML vs YAML vs JSON
| 维度 | TOML | YAML | JSON |
|---|---|---|---|
| 定位 | 手写配置 | 手写配置 / 复杂数据 | 机器数据交换 |
| 注释 | ✅ # | ✅ # | ❌ |
| 层级 | 显式 [表头]/点分键 | 缩进（敏感） | { } 嵌套 |
| 原生日期 | ✅ 四型 | ✅ | ❌ |
| 隐式类型转换 | ❌ | ✅（挪威问题） | ❌ |
| 锚点/引用 | ❌ | ✅ | ❌ |
| 典型 | Cargo.toml | k8s / CI | REST API |
选型速记：人手编辑 + 注释 + 日期 + 层级不深 → TOML；机器交换 / 对接 Web API → JSON；深层嵌套 + 锚点复用 → YAML。
六、术语
- 哈希表（hash table）：键到值的映射结构，即字典/对象；TOML 的解析目标就是它。
- 表（table）：
[t]声明的键值集合，映射到一层字典。 - 超级表（super-table）：点分键或子表头隐式创建的中间层表。
- 表数组（array of tables）：
[[t]]，一组同名表构成的数组。 - 内联表（inline table）：
{ }写在一行内的自包含表。 - 点分键（dotted key）：
a.b.c，用点号表达嵌套层级的键。 - 带偏移 / 本地日期时间：有无
Z/±hh:mm时区偏移之分，前者是绝对时刻。
七、权威链接
- TOML 官网 —— 首页与设计目标
- TOML v1.0.0 规范 —— 一手权威、逐条规则与示例
- toml-lang/toml —— 规范仓库与 Issue
- 官方 Wiki —— 各语言实现、验证器、编辑器支持目录
- PEP 518 ｜ PEP 621 —— Python
pyproject.toml标准 - Cargo 清单格式 —— Rust
Cargo.toml参考 - Taplo —— TOML 格式化工具与 LSP