本文目录
什么是 TOML？
TOML（Tom's Obvious, Minimal Language，即 Tom 的显而易见的极简语言）是一种旨在易读易写的配置文件格式。它由 Tom Preston-Werner（GitHub 的联合创始人）创建，能够清晰地映射到哈希表，并力求做到无歧义——每个 TOML 文档都只有唯一一种有效的解读方式。
TOML 是 Rust（Cargo.toml）、Python（pyproject.toml）以及众多静态站点生成器所首选的配置格式。它支持注释、日期时间字面量和嵌套表格，同时比 YAML 更简单，也比 JSON 对人类更友好。
TOML 语法规则
TOML 的语法设计力求极简且无歧义。以下是该语言的核心要素。
- 键/值对——最基本的构成单元，在每行上写作 key = value。键可以是裸键（不加引号）、带引号的键，或用于嵌套访问的点分键。
- 表格（Tables）——用 [table_name] 标头定义的分节，用于将相关的键/值对归为一组。表格可通过点分键或 [[array_of_tables]] 语法进行嵌套。
- 数组（Arrays）——用方括号定义的有序列表 [1, 2, 3]。所有元素必须是相同类型。多行数组允许使用尾随逗号。
- 日期时间字面量——TOML 原生支持 RFC 3339 日期，例如 2026-03-15T14:30:00Z、本地日期（2026-03-15）、本地时间（14:30:00）以及带偏移的日期时间。
- 多行字符串——三引号字符串（"""text"""）会保留换行，并允许无需转义序列即可书写长内容。字面字符串使用单引号（'no\escape'）。
常见的 TOML 模式
TOML 被广泛用于各类生态系统的项目配置文件中。
- Cargo.toml——Rust 的包管理器使用 TOML 来记录项目元数据、依赖项、构建配置文件和工作区配置
- pyproject.toml——Python 现代化的构建系统配置，由 PEP 517/518 定义，用标准化的 TOML 文件取代了 setup.py 和 setup.cfg
- Hugo 配置——Hugo 静态站点生成器使用 TOML（或 YAML/JSON）进行站点配置，包括主题、菜单、分类法和构建设置
- Netlify 配置——netlify.toml 为 Netlify 站点配置构建命令、重定向规则、环境变量和部署上下文
免费试用 —— 无需注册
在线校验 TOML →常见的校验错误
TOML 的设计本身就很严格——许多 YAML 会默默接受的错误在 TOML 中会直接失败。以下是最常见的校验问题。
- 重复键——TOML 禁止在同一表格中两次定义相同的键。这包括通过点分表示法设置的键以及常规的表格标头。
- 无效的日期格式——TOML 要求使用 RFC 3339 日期。常见错误包括漏掉 T 分隔符（写成 2026-03-15 14:30:00 而不是 2026-03-15T14:30:00），或用斜杠代替连字符。
- 数组类型混用——TOML 数组中的所有元素必须是相同类型。[1, "two", 3] 是无效的，因为它混用了整数和字符串。
- 未闭合的字符串——忘记闭合带引号的字符串，或使用了错误的引号类型，都会导致解析错误。要注意多行字符串中不匹配的三引号。
TOML 与 YAML、JSON 的对比
每种格式都各有所长，使其更适合某些特定的使用场景。
- 可读性——TOML 和 YAML 对人类都具有很高的可读性。TOML 使用显式语法（方括号、等号），而 YAML 依赖缩进。JSON 因需要引号且不支持注释，在配置方面可读性较差。
- 严格性——TOML 是三者中最严格的。它拒绝有歧义的结构，也没有隐式类型转换。YAML 的灵活性（把 yes/no 当作布尔值、裸字符串）常常导致意料之外的行为。
- 注释——TOML 和 YAML 都支持注释（TOML 使用 #，YAML 也使用 #）。JSON 完全不支持注释，这使其不太适合用作需要文档说明的配置文件。
常见问题
TOML 中的嵌套表格是如何工作的？
TOML 通过两种机制支持嵌套表格：点分键（a.b.c = value）和表格标头（[parent.child]）。二者创建的嵌套结构完全相同。对于表格数组（例如多个包依赖项），使用双方括号（[[array_name]]）。每个 [[array_name]] 块都会向数组中添加一个新元素。
TOML v1.0 与更早版本有什么区别？
TOML v1.0（于 2021 年 1 月发布）是首个稳定版本。相较于 1.0 之前的草案，主要变化包括：明确了日期时间的处理方式、正式确立了内联表格的语义，以及完善了表格数组的行为。大多数现代工具都使用 TOML v1.0——如果你正在编写新的配置文件，请以 v1.0 为目标。
如何将 YAML 转换为 TOML？
YAML 和 TOML 的数据模型不同，因此转换并不总是一一对应的。简单的键值结构和嵌套对象可以直接转换。而 YAML 的锚点、别名和复杂键等特性在 TOML 中没有对应物。对于大多数配置文件，转换是很直接的——将 YAML 字典映射为 TOML 表格，将 YAML 列表映射为 TOML 数组。