最后更新： 2026年4月

什么是 TOML 格式化？

TOML（Tom's Obvious Minimal Language）是 Tom Preston-Werner 于 2013 年创建的配置文件格式。它直接映射到哈希表，并对所有值使用显式类型。TOML 格式化工具将原始或风格不一致的 TOML 重新序列化为统一间距、规范缩进和标准键排序的形式。结果是整个项目遵循相同惯例的配置文件，使 diff 中的配置变更更易于审查。

TOML v1.0.0 规范于 2021 年 1 月定稿，其语法定义足够严格，任何合规解析器对相同输入都会产生完全相同的数据结构。格式化不会改变 TOML 文件的语义内容，仅调整空白字符、键的分组和引号风格。这意味着你可以自由格式化 TOML 文件，无需担心影响应用程序的行为。

与 JSON 不同，TOML 支持注释、原生日期时间类型以及多种字符串形式（基本字符串、字面字符串和多行字符串）。优秀的格式化工具会保留注释，并区分内联表和标准表头。它还能正确处理表数组，保持节的分组完整，使文件对人类和解析器都保持可读性。

Before · toml

After · toml

title="My App"
version="1.0.0"
debug=false
[database]
host="localhost"
port=5432
name="mydb"
[database.pool]
max_connections=25
timeout=30
[[servers]]
name="web"
host="web.example.com"
[[servers]]
name="api"
host="api.example.com"

title = "My App"
version = "1.0.0"
debug = false

[database]
host = "localhost"
port = 5432
name = "mydb"

[database.pool]
max_connections = 25
timeout = 30

[[servers]]
name = "web"
host = "web.example.com"

[[servers]]
name = "api"
host = "api.example.com"

为什么使用 TOML 格式化工具？

配置文件会随着不同团队成员的编辑而逐渐产生风格偏差：制表符与空格混用、部分键被不必要地加引号、表节失去视觉分组。TOML 格式化工具可一次性规范所有这些问题。

⚡

即时格式化

粘贴未格式化的 TOML，立即获得整洁、风格统一的输出。无需安装命令行工具，无需配置项目，无需等待构建步骤。

🔒

隐私优先处理

所有解析和格式化操作均在浏览器中本地运行。你的配置数据（包括凭据或内部主机名）不会离开你的设备。

✅

内置验证

格式化工具在重新序列化之前会先解析你的 TOML。如果输入存在语法错误，会给出包含问题行的清晰错误信息，因此格式化同时具备验证功能。

📋

无需注册

打开页面即可开始格式化，无需注册、无频率限制、无使用追踪。每次访问工具的功能完全相同。

TOML 格式化工具使用场景

前端开发

格式化 Cloudflare Workers 项目的 wrangler.toml 文件，或基于 Deno 的前端项目的 deno.toml 配置。整洁的格式化有助于在拉取请求中审查部署配置。

后端工程

统一多个 Rust 微服务的 Cargo.toml 文件格式。一致的格式使跨代码仓库扫描依赖版本和特性标志更加便捷。

DevOps 与 CI/CD

在提交前格式化 .goreleaser.toml、netlify.toml 或 Starship 提示符配置等文件。在 CI 流水线中添加格式化检查，以强制执行风格一致性。

质量保证与测试

快速格式化测试夹具，使其易于阅读和进行 diff 比较。当测试因配置差异失败时，格式化后的文件能让实际值与期望值的对比一目了然。

数据工程

格式化定义数据采集流水线的 Telegraf 或 InfluxDB 配置文件。这些文件通常多达数百行，一致的格式使其保持可维护性。

学习 TOML 语法

将文档或教程中的示例粘贴进来，观察格式化工具如何将其规范化。这是快速了解哪种括号风格、引号规则和表分组是标准写法的有效方式。

TOML 语法参考

TOML 有一套精简的语法结构。下表列出了 TOML v1.0.0 规范中定义的所有结构性元素。格式化工具会对所有这些元素应用一致的间距和分组规则。

语法	名称	备注
key = "value"	Basic key-value pair	Keys are bare or quoted; values are typed
[table]	Standard table	Creates a named section (hash table)
[a.b.c]	Dotted table	Shorthand for nested tables
[[array]]	Array of tables	Each [[name]] block appends to an array
key = """...\n"""	Multi-line basic string	Allows newlines, escapes processed
key = '''...\n'''	Multi-line literal string	Allows newlines, no escape processing
# comment	Comment	Extends to end of line; not in JSON output
{inline = true}	Inline table	Single-line table, no newlines allowed

TOML vs JSON vs YAML

TOML、JSON 和 YAML 解决相似的问题，但各有不同的取舍。

特性	TOML	JSON	YAML
注释	# 行注释	不支持	# 行注释
类型化值	字符串、整数、浮点数、布尔值、日期时间	字符串、数字、布尔值、null	推断（容易出错）
嵌套	[table] 表头	花括号	基于缩进
规范严格性	严格（唯一解析结果）	严格（RFC 8259）	宽松（多种合法解析结果）
日期/时间支持	4 种原生类型	无（使用字符串）	隐式（不稳定）
尾随逗号	不允许	不允许	无（没有逗号）

代码示例

以下示例展示如何在不同语言和工具中以编程方式格式化 TOML。每个示例读取文件、解析后输出格式化版本。

JavaScript (Node.js)

import { parse, stringify } from '@iarna/toml'
import fs from 'fs'

const raw = fs.readFileSync('config.toml', 'utf-8')
const doc = parse(raw)
const formatted = stringify(doc)
// stringify() outputs canonical TOML with consistent spacing
fs.writeFileSync('config.toml', formatted)

// Quick one-liner with npx:
// npx taplo fmt config.toml

Python

import tomllib   # Python 3.11+ (read-only)
import tomli_w   # pip install tomli-w (write)

# Parse and re-serialize to format
with open("config.toml", "rb") as f:
    data = tomllib.load(f)

formatted = tomli_w.dumps(data)
# tomli_w produces sorted keys, consistent quoting, and
# proper whitespace around = signs
print(formatted)

# CLI alternative: taplo fmt config.toml

package main

import (
    "fmt"
    "os"
    "github.com/BurntSushi/toml"
    "bytes"
)

func main() {
    var data map[string]interface{}
    _, err := toml.DecodeFile("config.toml", &data)
    if err != nil {
        fmt.Fprintln(os.Stderr, err) // parse error with line number
        os.Exit(1)
    }
    var buf bytes.Buffer
    enc := toml.NewEncoder(&buf)
    enc.Indent = "  "
    enc.Encode(data) // re-serialized with consistent formatting
    fmt.Print(buf.String())
}

CLI (taplo)

# Install taplo — the standard TOML toolkit
cargo install taplo-cli
# or: npm install -g @taplo/cli

# Format a single file in place
taplo fmt config.toml

# Format all .toml files in a project
taplo fmt

# Check formatting without modifying (CI-friendly)
taplo fmt --check

# Validate TOML syntax without formatting
taplo lint config.toml

常见问题

TOML 格式化工具的作用是什么？

TOML 格式化工具将文件解析为数据结构，然后以一致的空白字符、键排序和引号风格重新序列化。语义内容保持不变，只有视觉呈现发生变化：等号两侧的间距、表节之间的空行，以及嵌套值的缩进。

TOML 格式化对生产配置文件安全吗？

安全。格式化只改变空白字符和外观细节，格式化前后解析得到的数据结构完全相同。如果格式化工具遇到无效输入，会报错而不是输出错误的结果。你可以通过解析两个版本并对比结果对象来验证这一点。

TOML 与 JSON 有何不同？

TOML 支持注释、原生日期时间类型、多行字符串，以及用于组织嵌套数据的表头，而 JSON 均不支持。TOML 专为供人类阅读和编辑的配置文件设计，JSON 则为程序间的数据交换设计。JSON 不支持注释，这使得在配置中内联记录决策变得困难。

能否通过命令行格式化 TOML？

可以。Taplo 是使用最广泛的 TOML 格式化命令行工具。通过 cargo install taplo-cli 或 npm install -g @taplo/cli 安装，然后运行 taplo fmt 格式化项目中所有 .toml 文件。它支持通过 taplo.toml 或 .taplo.toml 文件配置自定义规则。

格式化会保留 TOML 文件中的注释吗？

这款基于浏览器的格式化工具将输入解析为数据结构后重新序列化，此过程会丢失注释。如果需要保留注释，请使用支持 CST 的工具，如 Taplo（命令行）或 toml-edit（Rust 库），它们基于具体语法树而非解析后的数据进行操作。

TOML 格式化与 TOML 验证有何区别？

验证检查文件是否符合规范，不符合时报告错误。格式化更进一步：先验证输入，再以规范化的风格重写。每次格式化操作都以验证为第一步，因此格式化成功的文件必然是有效的。

哪些项目使用 TOML 作为配置格式？

Rust 的 Cargo（Cargo.toml）、Python 打包生态（pyproject.toml）、Hugo 静态网站、Deno（deno.toml）、Cloudflare Workers（wrangler.toml）、InfluxDB、Telegraf 以及 Starship 提示符均使用 TOML。该格式在 2015 年 Rust 将其作为包清单标准格式后获得广泛普及。

TOML 格式化工具