TOML：为人类而生的配置文件语言

在软件开发的世界里，配置文件无处不在。它们如同应用程序的“说明书”，指导着程序的行为和参数设定。长期以来，JSON 以其简洁和广泛的机器支持成为配置场景的常用选择，但其缺乏注释、括号密集的缺点在人手写和维护时并不友好；YAML 虽强调人类可读性，但其长达数十页的规范、缩进敏感的特性以及“挪威问题”（no 被误解析为 false 等陷阱）也让不少开发者望而却步。

这时，一个旨在平衡简洁性、可读性和精确性的格式应运而生——TOML。

什么是 TOML？

TOML 全称是 Tom’s Obvious, Minimal Language（汤姆的显而易见的最小化语言），由 GitHub 联合创始人 Tom Preston-Werner 于 2013 年创建。

它的设计目标非常明确，体现在三个核心宗旨上：

  • 语义明显且易于阅读（Obvious）：语法力求贴近人类自然阅读习惯，一眼就能看懂配置的含义。
  • 最小化（Minimal）：力求保持语言简单，不引入复杂特性和潜在歧义。
  • 无歧义地映射为哈希表：能被轻松、明确地解析成各种编程语言中的数据结构（字典/对象）。

正因如此，TOML 被设计为一种专门服务于配置文件的格式，而非通用的数据序列化工具。

TOML 与其他格式的对比

为了更清晰地理解 TOML 的定位，可以将它与常见的 JSON 和 YAML 进行对比：

特性TOMLJSONYAML
核心定位人类友好的配置文件机器间的数据交换人类可读的数据序列化
注释支持✅ 原生支持 # 注释❌ 不支持✅ 支持 # 注释
可读性极高，语法清晰，结构直观较差，大量括号和引号高，但依赖缩进
学习曲线平缓，语法规则简单明确平缓陡峭，规范复杂，隐式类型转换多
主要痛点相对较新，生态仍在成长缺乏注释，不适合手写维护缩进敏感，解析规则复杂，存在安全风险
应用场景项目配置（如 Cargo.toml, pyproject.toml）Web API 数据传输、通用数据存储复杂配置（如 Kubernetes, Ansible）

TOML 同时吸收了 JSON 和 YAML 的优点：它像 JSON 一样结构明确无歧义，又像 YAML 一样注重人类可读性并支持注释。

TOML 基础语法详解

TOML 的语法设计在 INI 文件格式上进行了标准化和增强，上手非常简单，核心是键值对。

1. 注释 (Comments)

与许多配置文件一样，TOML 使用 # 来表示注释。注释是对配置项最好的解释，也是 YAML 相比 JSON 的一大优势，而 TOML 将其作为一等公民。

# 这是一个全行注释
key = "value"  # 这是一个行末注释

2. 键值对 (Key-Value Pairs)

TOML 文档最基本的构成单元是键值对。格式为 键 = 值，等号两边必须有空格。

name = "TOML 示例"
version = 1.0
enabled = true

键名有三种形式：

  • 裸键 (Bare Key)：只能包含 ASCII 字母、数字、下划线和短横线（A-Za-z0-9_-）。这是最佳实践，最常用。例如：key = "value", bare-key = "value"。
  • 引号键 (Quoted Key)：使用双引号或单引号包裹，可以包含更广泛的字符（如空格、点、中文）。例如："127.0.0.1" = "value", 'character encoding' = "utf-8"。
  • 点分隔键 (Dotted Key)：用点（.）将裸键或引号键串联起来，用来表示嵌套关系，这是 TOML 表示层级结构的主要方式。例如：physical.color = "orange"。

3. 数据类型

TOML 支持多种丰富的数据类型，每种都有清晰明确的语法。

字符串 (Strings)

TOML 提供了四种字符串表示方式，非常灵活：

  • 基本字符串 (Basic String)：由双引号包裹，支持常见的转义序列（如 \n, \t, \"）和 Unicode 转义（\uXXXX）。这是最常用的字符串形式。
  str = "我是一个字符串。\"你可以引我\"。\n新的一行。"
  • 多行基本字符串 (Multi-line Basic String)：由三个双引号包裹，主要用于表示长文本，会保留内部的换行和缩进。
  str1 = """
  Roses are red
  Violets are blue"""
  • 字面量字符串 (Literal String)：由单引号包裹，不支持任何转义，所见即所得。非常适合写 Windows 路径或正则表达式，避免反斜杠带来的困扰。
  winpath = 'C:\Users\nodejs\templates'
  regex = '<\i\c*\s*>'
  • 多行字面量字符串 (Multi-line Literal String)：由三个单引号包裹，是多行版本的字面量字符串。

数值 (Numbers)

  • 整数 (Integer)：支持十进制、二进制（0b）、八进制（0o）、十六进制（0x），还支持千位分隔符（_）提高大数字可读性。
  int = 42
  hex = 0xDEADBEEF
  sep = 1_000_000
  • 浮点数 (Float)：支持标准小数和科学计数法。
  float1 = 3.14
  float2 = 6.626e-34

布尔值 (Booleans)

必须是小写的 true 或 false，避免了 YAML 中的歧义。

enabled = true

日期与时间 (Datetime)

TOML 将日期时间作为一种原生数据类型，支持 RFC 3339 标准格式，非常方便。

date1 = 1979-05-27T07:32:00Z          # 带 UTC 时区
date2 = 1979-05-27T00:32:00-07:00     # 带时区偏移
date3 = 1979-05-27                    # 仅日期
time1 = 07:32:00                      # 仅时间

4. 表格 (Tables)

表格是 TOML 的核心概念，用于组织和管理键值对，可以理解为其他语言中的“对象”或“字典”。表格通过表头来定义，表头使用方括号 [] 包裹，独占一行。

[owner]        # 定义一个名为 'owner' 的表
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00Z

5. 嵌套与点分隔

TOML 推荐使用点分隔键来定义嵌套表格，这种方式比 JSON 和 YAML 的嵌套更为扁平直观。

[servers]                # 定义 'servers' 表
[servers.alpha]          # 定义嵌套的 'alpha' 表，是 'servers' 的子表
ip = "10.0.0.1"
[servers.beta]           # 定义嵌套的 'beta' 表，同样是 'servers' 的子表
ip = "10.0.0.2"

这等价于 JSON 的 { "servers": { "alpha": { "ip": "10.0.0.1" }, "beta": { "ip": "10.0.0.2" } } } 结构。

6. 内联表 (Inline Tables)

内联表提供了一种紧凑的写法，用于在行内表示一个简单的表，适合包含少量键值对的场景，在 TOML 1.1.0 版本后变得更加灵活。

point = { x = 1, y = 2 }  # 等价于 [point] x=1 y=2

# TOML 1.1.0 允许内联表跨多行，并支持末尾逗号
name = {
    first = "Tom",
    last = "Preston-Werner",
}

7. 数组 (Arrays)

数组使用方括号包裹，元素用逗号分隔。与 JSON 不同，TOML 的数组内元素类型可以混用（如 [ [1, 2], ["a", "b"] ]）。

ports = [ 8001, 8002, 8003 ]  # 单行数组
hosts = [                     # 多行数组
    "alpha",
    "omega"
]

8. 表格数组 (Array of Tables)

这是 TOML 中最强大的特性之一。当你需要一个对象列表时，可以使用双方括号 [[ ]] 定义。每个 [[表名]] 块都会成为该数组中的一个元素。

[[products]]          # 数组中的第 1 个元素
name = "Hammer"
sku = 738594937

[[products]]          # 数组中的第 2 个元素（空表）

[[products]]          # 数组中的第 3 个元素
name = "Nail"
sku = 284758393

这等价于 JSON 的 { "products": [ {"name": "Hammer", "sku": 738594937}, {}, {"name": "Nail", "sku": 284758393} ] } 结构。

表格数组的强大之处在于可以嵌套，通过在子表上也使用 [[ ]] 来定义属于当前数组元素的子对象数组。

TOML 1.1.0 版本的新特性

TOML 社区于 2025年12月18日 正式发布了 1.1.0 版本。这个版本带来了多项实用的改进，让配置编写更加舒适：

  1. 更灵活的内联表：现在内联表允许换行和末尾逗号，极大地提升了在复杂场景下的可读性和易编辑性。
    toml # TOML 1.1.0 合法 person = { name = "Alice", age = 30, }
  2. 新增字符串转义：添加了 \xHH（表示一个字节的十六进制）和 \e（转义字符）两种新转义序列，灵活性更强。
    toml null_byte = "null byte: \x00" csi = "\e[" # ESC 字符
  3. 日期和时间可省略秒：日期-时间和时间值中的秒数现在变成了可选，可以书写得更简洁。
    toml dt = 2010-02-03 14:15 # 只到分钟 t = 14:15 # 只到分钟
  4. 裸键允许更多字符：对于裸键，其允许的字符范围进行了讨论和调整。虽然最初讨论过允许非英文字母，但最终正式版未包含此特性。

注意：尽管 v1.1.0 引入了许多新特性，但并非所有语言的解析库都已经实现了全部内容。在使用前，请确认你所使用的库是否支持所需的新语法。

TOML 的应用场景与局限性

最佳应用场景

TOML 最适合那些需要由人来频繁阅读、编写和修改的配置文件。它在以下生态中已是标准：

  • 项目元数据和依赖管理：如 Rust 的 Cargo.toml，Python 的 pyproject.toml。
  • 应用程序配置：数据库连接、服务端口、功能开关等。
  • 工具链配置：各类现代构建工具、代码格式化工具的配置文件。

主要局限性

  • 非通用序列化格式：TOML 文件顶层必须是一个哈希表（Table），不能直接是数组或基础类型，因此不适合序列化任意数据结构，机器间数据交换仍以 JSON 为首选。
  • 嵌套极深的结构可读性欠佳：在处理非常深的嵌套结构时，TOML 的 [[a.b.c]] 语法可读性可能不如 JSON 和 YAML 直观，但多行内联表缓解了这个问题。

总结

TOML 的设计哲学是“配置应该对人类友好”。它巧妙地在 INI 的简洁、JSON 的清晰和 YAML 的易读之间找到了平衡点，同时规避了 YAML 的复杂性和 JSON 缺乏注释的缺陷。对于绝大多数应用程序和项目的配置场景而言，TOML 凭借其明确的语法、原生注释、丰富的数据类型支持，以及 Rust、Python 等主流生态的背书，已经成为极具吸引力的现代配置方案。

作者

老丹

关注我
其他文章