TOML文件格式详解

原创于 2025-10-15 10:46:58 发布 · 869 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#toml #pyproject.toml #python

TOML 专栏收录该内容

1 篇文章

订阅专栏

TOML 的核心理念是：一个明显的、最小化的配置文件格式，能无歧义地映射为哈希表。 它的语法旨在清晰易读，并且能简单地解析为各种编程语言中的数据结构。

1. 什么是 TOML？

TOML 是 “Tom’s Obvious, Minimal Language” 的缩写，由 Tom Preston-Werner（GitHub 联合创始人）创建。它被设计为用于配置文件的，与 JSON 或 YAML 类似，但更强调可读性。

你会在很多地方看到它，例如：

Rust 的包管理器 Cargo 使用 Cargo.toml。
Python 的包管理器 Poetry 使用 pyproject.toml。
Go 的很多项目使用 go.mod（虽然不是标准 TOML，但风格类似）。
很多现代应用和框架 的配置文件。

2. 基本语法与数据类型

TOML 文件由键值对组成。

2.1 字符串

# 基本字符串，使用双引号
name = "Alice"
quote = "She said, \"Hello!\""

# 多行基本字符串，使用三个双引号，内部的换行和引号会被保留
poem = """
Roses are red,
Violets are blue,
TOML is awesome,
And so are you.
"""

# 字面量字符串，使用单引号，不处理转义符
path = 'C:\Users\Documents\file.txt' # 这里面的 \U, \D, \f 都不会被转义

# 多行字面量字符串，使用三个单引号
script = '''
echo "Hello World"
echo 'This is a test'
'''

2.2 数字

# 整数
age = 25
negative = -10

# 浮点数
height = 1.75
price = 19.99

# 科学计数法
avogadro = 6.022e23

# 支持下划线增强可读性（类似于编程语言）
big_number = 1_000_000
hexadecimal = 0xDEAD_BEEF
binary = 0b1101_0101

2.3 布尔值

is_enabled = true
debug_mode = false

2.4 日期与时间

TOML 对日期和时间有原生支持。

# 偏移日期时间（带时区）
created_at = 2023-10-27T12:34:56+08:00

# 本地日期时间（不带时区）
local_meeting = 2023-10-27T14:00:00

# 本地日期
birthday = 2023-10-27

# 本地时间
alarm_clock = 07:30:00

3. 核心数据结构

3.1 表（Table） - 核心概念

表相当于其他语言中的字典、对象或哈希表，用于组织数据。

# 这是一个顶层的表，键是 `user`
[user]
name = "Bob"
age = 30

# 等价于 JSON: { "user": { "name": "Bob", "age": 30 } }

3.2 内联表（Inline Table）

紧凑地表示一个表，写在一行内，用花括号 {} 括起来。

user = { name = "Bob", age = 30, active = true }
# 等价于上面的 [user] 定义

3.3 表数组（Array of Tables）

表示一个对象的数组，使用双方括号 [[ ... ]]。

# 定义一个 products 表数组
[[products]]
name = "Hammer"
sku = 738594937

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

这等价于以下的 JSON：

{
  "products": [
    { "name": "Hammer", "sku": 738594937 },
    { "name": "Nail", "sku": 284758393, "color": "gray" }
  ]
}

4. 完整示例与解析

让我们看一个完整的、接近真实场景的 TOML 配置文件。

# 这是一个服务器应用的配置文件示例

title = "My Awesome App"

[database]
  # 数据库连接信息
  enabled = true
  host = "localhost"
  port = 5432
  username = "app_user"
  password = "super_secret" # 注意：密码不应明文存储在生产环境！
  name = "app_db"

  # 连接池配置 (内联表)
  connection_pool = { max_connections = 20, timeout_seconds = 30 }

  # 支持的数据库类型数组
  supported_types = [ "postgresql", "mysql" ]

[servers]
  # 主服务器配置
  [servers.alpha]
  ip = "10.0.0.1"
  role = "frontend"

  # 备份服务器配置
  [servers.beta]
  ip = "10.0.0.2"
  role = "backend"

# 用户列表 (表数组)
[[users]]
id = 1
name = "Alice"
hobbies = [ "reading", "hiking" ]

[[users]]
id = 2
name = "Bob"
hobbies = [ "gaming" ]

# 缓存配置 (另一个顶层表)
[cache]
  redis_url = "redis://localhost:6379"
  ttl_minutes = 60

这个 TOML 文件解析后，在任何支持 TOML 的编程语言中都会变成一个结构化的数据对象。例如在 Python 中使用 tomli/tomllib 库：

# Python 3.11+ 有内置的 tomllib
import tomllib

with open("config.toml", "rb") as f:
    config = tomllib.load(f)

print(config["title"]) # 输出: My Awesome App
print(config["database"]["host"]) # 输出: localhost
print(config["users"][0]["name"]) # 输出: Alice
print(config["servers"]["alpha"]["role"]) # 输出: frontend

5. TOML vs. JSON vs. YAML

特性	TOML	JSON	YAML
可读性	非常高，语法接近原生英语	较低，括号和引号较多	高，依赖缩进
注释	支持 (`#`)	不支持	支持 (`#`)
严格性	严格，语法简单明确	非常严格	灵活，但可能导致复杂性
原生类型	支持日期时间	不支持日期时间	支持日期时间
学习曲线	非常平缓	平缓	较陡峭（有复杂特性）
主要用途	配置文件	数据序列化、API	配置文件、数据序列化

总结

TOML 非常适合人类编写和阅读的配置文件。它的设计目标就是清晰和最小歧义。
核心结构是 键值对、表和 表数组。
它支持丰富的数据类型，特别是对日期时间的原生支持非常实用。
当你需要一个简单、直观且功能足够的配置格式时，TOML 是一个绝佳的选择。

Python 官方文档 - tomllib 模块：https://docs.python.org/zh-cn/3.12/library/tomllib.html 。这是学习tomllib模块最权威的资料，详细介绍了模块的函数、异常、数据类型转换等内容，包含丰富的示例代码，适合深入学习和查阅。
TOML 官方网站：https://toml.io 。TOML 语言的官方网站，在这里可以深入了解 TOML 的语法规范、设计理念等，有助于更好地理解tomllib模块在处理 TOML 文件时的原理。