TOML 语法速查表 - TOML 配置文件常用命令大全
Cargo、Hugo 等现代工具的配置都用 TOML，它用明确的 [table] 和 key = value 让配置比 JSON 更易读，还支持注释。这份速查按 6 组整理：基础类型、日期时间、四种字符串写法、数组与表格、数组表格，以及一份可直接套用的 Cargo.toml 示例。写依赖表或嵌套 section 时对照结构，遇到字符串转义、日期时区时按组查询，避免常见的类型与结构歧义。读完你就能独立维护 Cargo.toml 这类 TOML 配置。
基础类型 11
# 这是注释key = "value"key = 'value'int = 42hex = 0xFFoct = 0o17bin = 0b101num = 1_000_000float = 3.14flt = infbool = true日期时间 5
date = 2026-07-19time = 14:30:00datetime = 2026-07-19T14:30:00datetime = 2026-07-19T14:30:00Zdatetime = 2026-07-19T14:30:00+08:00字符串 4
str = "Hello\nWorld"str = """Hello\nWorld"""str = 'C:\\path\\to\'str = '''C:\\path\\to\'''数组与表格 6
array = [1, 2, 3]array = [
1,
2,
3,
][table][table.subtable]physical.color = "orange"inline = { key1 = "value1", key2 = 2 }数组表格 4
[[products]]name = "Apple"[[products]]name = "Banana"Cargo.toml 示例 8
[package]name = "myapp"version = "0.1.0"edition = "2021"[dependencies]serde = "1.0"serde = { version = "1.0", features = ["derive"] }[dev-dependencies]命令示例
一份完整的 Cargo.toml 骨架
[package]
name = "myapp"
version = "0.1.0"
edition = "2021"
[dependencies]
serde = "1.0"
serde = { version = "1.0", features = ["derive"] }
[dev-dependencies]简写与带 feature 的写法不能对同一个包各写一行，后一行会覆盖前一行。带 feature 的写法才能开启派生支持，简写只声明版本区间。
数组表格：同一个名字重复声明即追加元素
[[products]]
name = "Apple"
[[products]]
name = "Banana"两个 name 分别属于两个独立的元素，不构成重复键。若写成 [products]，第二次声明就会因重复定义直接报错。条目顺序即声明顺序。
字符串的四种写法与各自的转义规则
str = "Hello\nWorld"
str = 'C:\\path\\to'
str = """Hello\nWorld"""
str = '''C:\\path\\to'''双引号形式会解析 \n 等转义，单引号形式原样保留反斜杠——这正是 Windows 路径适合用单引号的原因。三引号形式允许跨行书写，是否解析转义同样由引号种类决定。
表格、内联表格与点号键三种嵌套写法
[table]
[table.subtable]
physical.color = "orange"
inline = { key1 = "value1", key2 = 2 }三者生成的嵌套结构一致，选哪种看可读性：相关设置连续用点号键最紧凑，需要成块展开时用子表格，单行小结构用内联表格最省事。
常见坑与注意事项
- bool 必须写成不带引号的 true/false，写成 "true" 会变成字符串，程序拿到的是文本而不是开关，配置校验常在这里静默失败。
- 同一个包名不要同时写简写和带 feature 的两种声明，后一行会覆盖前一行，feature 可能整个失效。
- 数组表格元素之间不要共用同一个 [table] 名称，条目数量不确定时写成 [[array]]，否则重复声明直接报重复定义。
- 跨系统传递的时间戳必须带时区偏移或用 UTC，不带时区的值在不同机器时区下会指向不同时刻。
- TOML 只支持 # 行注释且没有块注释，把注释写成 C 风格或用分号起头都会被当成无效语法。
提示
- TOML 目标是可读性优先，比 JSON 更适合配置文件。
- 字符串分基本字符串（双引号，支持转义）和字面量字符串（单引号，不转义）。
- 表格 [table] 和数组表格 [[array]] 是 TOML 的核心结构。
常见问题
[table] 和 [[array]] 到底有什么区别？
[table] 定义的是一个具名的键值区块，同名表只能出现一次；[[array]] 定义的是数组的每一个元素，同一个名字可以重复声明，每重复一次就往数组里追加一个条目。[[products]] 后面的 name、version 等键属于当前这一个元素，而不是表本身。实践上的差别在于：结构不确定、条目数量由内容决定（比如一串依赖、一组 CI 任务）用 [[array]]；结构固定只是一组命名参数（比如包信息、依赖表）用 [table]。把数组表格误写成普通表，重复声明就会报重复定义错误。
基本字符串和字面量字符串该怎么选？
看值里有没有需要表达的转义与特殊字符。key = "value" 是基本字符串，会解析 \n、\t、反斜杠和双引号这些转义序列，需要换行或含特殊字符时用它；key = 'value' 是字面量字符串，内容原样保留，一个转义都不处理。Windows 路径是最典型的场景：C:\Users 里的反斜杠在基本字符串里必须写成双反斜杠，否则会被当成转义起始符；用字面量字符串就能直接写。对应地，多行写法也有两种——三引号基本字符串保留转义，三引号字面量字符串完全原样。
布尔值写成 "true" 会发生什么？
它会变成字符串，而不是布尔值。加引号的 "true" 在 TOML 里是普通字符串，与 true 完全是两种类型，这个区别在配置校验或代码读取时会直接体现出来——程序拿到的是一段文本而不是开关。TOML 的布尔值只有小写的 true 和 false，且不能加引号。同类问题还有整数下划线：num = 1_000_000 是合法整数（用于提升可读性），但 num = 1_000_000.0 之类混用会得到浮点数，类型与预期不符。
点号键和子表格是一回事吗？
结构上等价，写法不同。physical.color = "orange" 属于点号键，它可以在文件任意位置定义，键名里的点就是层级分隔符；[physical.color] 是子表格，需要独立成行。两者最终形成的嵌套结构相同，所以混用不会冲突，但可读性差异明显：一段相关配置用点号键连续写更紧凑，而需要在某个区块里写多行内容时用子表格更清晰。内联表格 inline = { key1 = "value1", key2 = 2 } 则是第三种形式，适合一行写完的小结构。
日期时间几种写法怎么选？
看你是否需要时区信息。date = 2026-07-19 是本地日期，time = 14:30:00 是本地时间，datetime = 2026-07-19T14:30:00 是不带时区的本地日期时间；末尾加 Z 表示 UTC，加 +08:00 这类偏移表示带时区偏移。跨系统传递的时间应当始终带时区偏移或用 UTC，因为不带时区的值在不同机器、不同容器时区下会指向不同时刻，这类隐式转换造成的偏差很难追溯。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。