随记
TOML 配置文件：明确类型的现代配置格式
介绍 TOML 键值、表、数组、字符串和日期时间，比较它与 INI、YAML、JSON、.env 的选型差异。
发布于 2026年7月24日
TOML 配置文件：明确类型的现代配置格式
TOML 是专门面向配置文件设计的格式，目标是语义直观、容易阅读，并能无歧义地映射为键值表。它保留了 INI 的简洁外观，同时补上明确的数据类型、数组、嵌套表和日期时间。
TOML 很适合项目元数据、开发工具和中等复杂度的应用配置。它不追求像 YAML 那样表达任意复杂的数据图，而是让常见配置保持可预测。
一、完整示例
[app]
name = "config-demo"
debug = false
features = ["search", "cache"]
[server]
host = "127.0.0.1"
port = 8080
[database]
pool_size = 10
方括号定义表。字符串必须加引号，布尔值和整数有明确类型，数组也有标准语法，因此不需要像 INI 那样约定逗号分隔字符串。
二、常用语法
键值与注释
name = "config-demo"
debug = false
port = 8080
ratio = 0.75
# 后面的内容是注释。键区分大小写；裸键可使用字母、数字、下划线和连字符，其他字符应使用引号。一个键不能定义多次。
表、点号键与数组
表用于分组：
[server]
host = "127.0.0.1"
port = 8080
点号键也能创建层级：
database.pool_size = 10
database.timeout = 5.0
数组使用方括号，允许换行和末尾逗号：
features = [
"search",
"cache",
]
重复对象使用数组表：
[[servers]]
name = "primary"
port = 8080
[[servers]]
name = "backup"
port = 8081
TOML 还原生支持带时区日期时间、本地日期时间、日期和时间。只有确实需要时间语义时才使用这些类型；版本号和编号仍应写成字符串。
三、字符串与类型
双引号基本字符串支持 \n、\t、\\ 等转义；单引号字面量字符串不解释反斜杠，适合 Windows 路径和正则表达式：
windows_path = 'C:\Program Files\Config Demo'
message = "first line\nsecond line"
整数、浮点数、布尔值、日期时间、数组和内联表都是标准类型。TOML 没有 null；如果某个设置可缺省，通常直接省略该键，并由应用提供默认值。
四、适用场景
TOML 适合：
- 由开发者或高级用户直接维护的应用配置。
- 包管理、构建系统和开发工具的项目元数据。
- 需要注释、明确类型和中等层级结构。
- 希望从 INI 升级，但不需要 YAML 的全部表达能力。
- 需要稳定、容易审查的版本库差异。
大量深层对象、复杂对象列表或平台已经采用 YAML 时，不必强行改用 TOML；纯机器数据交换则通常选择 JSON。
五、与其他格式对比
| 对比格式 | TOML 的优势 | TOML 的不足 |
|---|---|---|
| INI | 类型、数组、表和编码规则更明确 | 旧软件支持度不如 INI |
| YAML | 简单配置语义更直观，缩进不决定层级 | 深层结构和大量重复对象较啰嗦 |
| JSON | 支持注释，更适合人工维护和项目元数据 | 通用数据交换生态不如 JSON |
.env |
原生类型和分组能力完整 | 不能像 .env 那样直接注入进程环境 |
TOML 表面像 INI，但语法更严格。不能假设任何 INI 文件都是合法 TOML，也不能把未加引号的普通单词当作字符串。
六、常见错误与安全提醒
- 字符串必须加引号，只有布尔值、数字和日期时间等标准类型可以裸写。
- 同一个键或表不能重复定义。点号键和表头混用时尤其要避免重新声明。
- 注意表的作用域。表头后的键一直属于该表，直到下一个表头或文件结束。
- 不要用日期类型保存版本号，也不要用数字保存有前导零的编号。
- 固定规范版本。TOML 1.1.0 发布较新，目标解析器若只支持 1.0.0，应避免使用仅由新版增加的语法并准备兼容测试。
- 避免把秘密直接提交到 TOML 文件。敏感值仍应通过环境或秘密管理系统注入。
- 语法校验后继续做业务校验，包括未知键、取值范围、必填项和互斥选项。
七、选型建议
对于新建的开发工具、项目清单和中等规模应用配置，TOML 是很平衡的选择。它比 INI 更明确、比 JSON 更适合注释、又比 YAML 少一些隐式行为。
在采用前，应先确认部署环境中的解析库支持目标 TOML 版本。团队若已经围绕 YAML Schema 或某个平台形成成熟流程，保持生态一致通常比更换语法更重要。