TOML

2 个工具

TOML转JSON将 TOML 格式转换为 JSON 格式 TOML 格式化工具格式化并验证 TOML 配置文件

ToolDeck 的 TOML 工具让你可以直接在浏览器中格式化、验证和转换 TOML 配置文件——无需安装，无需账号，数据不会上传至任何服务器。TOML 格式化工具会解析你的 TOML 输入，并以统一的缩进、规范的键排序重新序列化，同时内联显示精确定位语法问题的验证错误。TOML 转 JSON 工具将 TOML 文档转换为等效的 JSON 格式，完整保留数据类型，包括日期时间、内联表和表数组。两个工具均完全在客户端运行，因此你的配置文件——通常包含数据库凭据、API 端点和部署密钥——始终留在你的设备上。如果需要反向转换，JSON 分类下的 JSON 转 TOML 工具可处理该转换。

什么是 TOML 工具？

TOML（Tom's Obvious, Minimal Language）是一种以明确、无歧义语法为核心设计的配置文件格式。由 GitHub 联合创始人 Tom Preston-Werner 创建，TOML 于 2013 年首次发布，并于 2021 年 1 月完成 1.0 规范。该格式可无歧义地映射到哈希表：每个 TOML 文件定义一棵由键值对组成的树，通过表（由 [方括号] 标记的节）进行组织。与 YAML 不同，TOML 不依赖缩进来表示结构，从而消除了整类与空白相关的解析错误。与 JSON 不同，TOML 支持注释、原生日期/时间类型和多行字符串——这些是配置文件所需的特性，而 JSON 从未被设计为提供这些功能。

TOML 工具将读取、验证和转换 TOML 文件的机械性工作自动化。格式化工具规范缩进和键排序，使配置文件在团队中保持可读性，即便多位贡献者编辑同一文件也不例外。转换工具在 TOML 与 JSON 之间进行翻译，当某个库或 API 需要 JSON 输入而你的数据源是 TOML 配置时非常实用。验证功能可在语法错误——缺少闭合括号、重复键或无效的日期时间字面量——导致应用启动失败之前将其捕获。

这些任务在 Rust 项目（Cargo.toml 是包清单）、Python 打包（pyproject.toml 通过 PEP 518 和 PEP 621 取代 setup.py 成为标准构建配置）、Hugo 静态站点（默认使用 TOML 进行站点配置）以及将配置存储在 TOML 文件中的各类基础设施中频繁出现。TOML 规范在 toml.io 维护，所有主流编程语言均有对应的解析器。

为什么在 ToolDeck 上使用 TOML 工具？

ToolDeck 的 TOML 工具使用 JavaScript 在浏览器标签页内解析和处理所有内容。不向服务器传输任何配置数据，无需账号，页面首次加载后即可离线使用。

🔒

默认私密

配置文件通常包含敏感值——数据库 URL、API 密钥、部署目标。ToolDeck 完全在客户端处理 TOML，数据不会离开你的浏览器。适合用于专有项目和内部基础设施配置。

⚡

即时反馈

粘贴 TOML，立即查看格式化输出或 JSON 结果。语法错误会以行号和描述的形式上报。无需等待安装 CLI 工具或等待构建步骤完成。

🔄

精确的类型转换

TOML 转 JSON 工具将 TOML 特有的类型（如带时区偏移的日期时间、本地日期和本地时间）保留为 ISO 8601 字符串。整数和浮点数的精度得以保持。表数组正确映射为 JSON 对象数组。

🌐

无需安装

在任何搭载现代浏览器的设备上均可使用。当你在没有惯用开发环境的机器上审查 Pull Request，或需要快速验证同事的 TOML 文件时非常实用。

TOML 工具使用场景

TOML 的格式化、验证和转换需求存在于不同角色和项目类型中。Rust 开发者每天与 Cargo.toml 打交道。Python 开发者通过 pyproject.toml 配置构建和工具。DevOps 工程师管理以 TOML 格式交付的应用配置。以下场景展示了基于浏览器的 TOML 工具相比编写一次性脚本或安装 CLI 工具节省时间的情况。

Cargo.toml 整理

合并多个依赖项添加后，Rust 项目的 Cargo.toml 格式不一致。提交前通过 TOML 格式化工具规范缩进和键顺序。

pyproject.toml 转 JSON

CI 流水线需要 JSON 格式的构建元数据，但数据源是 pyproject.toml。使用 TOML 转 JSON 工具生成 JSON 表示，并在将转换脚本化到流水线之前验证映射关系。

配置迁移

将应用从基于 JSON 的配置迁移到 TOML（或反向迁移）。TOML 转 JSON 工具让你可以并排比较两种表示形式，以确认数据类型、嵌套结构和数组语义得以保留。

语法调试

TOML 配置文件在应用启动时解析失败，错误信息含糊不清。将其粘贴到 TOML 格式化工具，获取语法错误的具体行号和列号，以及解析器预期内容的说明。

文档生成

编写同时包含 TOML 和 JSON 格式配置示例的文档。通过 TOML 转 JSON 工具转换规范的 TOML 示例，使两个版本保持同步，无需手动转录。

学习 TOML 语法

TOML 新手可以通过在 TOML 格式化工具中编写 TOML 来体验该格式，实时查看验证错误，并将结构与格式化输出进行比较。这比单独阅读规范文档要高效得多。

TOML 数据类型参考

TOML v1.0 定义了以下数据类型。转换为 JSON 时，每种类型映射到特定的表示形式。下表涵盖每种 TOML 类型的语法、示例和转换行为。

类型	语法	示例	JSON 映射
字符串	"..." 或 '...'	name = "TOML"	JSON 字符串。基本字符串支持转义序列（\n、\t、\u）。字面量字符串（'...'）将反斜杠视为普通字符。
整数	十进制、0x、0o、0b	port = 8080	JSON 数字。支持十六进制（0xDEAD）、八进制（0o755）、二进制（0b1010）及下划线分隔符（1_000）。
浮点数	含 . 或 e 的数字	pi = 3.14159	JSON 数字。支持 inf、-inf 和 nan（转换为 JSON 时映射为 null 或字符串，因为 JSON 没有 NaN 类型）。
布尔值	true / false	enabled = true	JSON 布尔值。仅小写的 true 和 false 有效。
带时区日期时间	RFC 3339	2024-01-15T09:30:00Z	JSON 字符串（ISO 8601）。包含时区偏移。JSON 没有原生日期时间类型。
本地日期时间	日期 T 时间	2024-01-15T09:30:00	JSON 字符串。不含时区信息。适用于挂钟时间。
本地日期	YYYY-MM-DD	2024-01-15	JSON 字符串。不含时间部分的日期。
本地时间	HH:MM:SS	09:30:00	JSON 字符串。不含日期或时区的时间。
数组	[值, ...]	ports = [8080, 8443]	JSON 数组。TOML v1.0 中数组可以包含异构类型，但在 v0.5 中必须是同构类型。
表	tomlCategoryContent.r10Syntax	[database]	JSON 对象。标准表使用 [方括号]。内联表在单行中使用花括号。

TOML v1.0.0 规范（toml.io）是当前稳定版本。表数组使用 [[双括号]] 定义重复的表条目，映射为 JSON 对象数组。

如何选择合适的 TOML 工具

ToolDeck 提供三个处理 TOML 文件的工具：两个位于 TOML 分类，一个位于 JSON 分类用于反向转换。请根据你的任务选择合适的工具。

1
如果你需要重新缩进 TOML 文件、规范键排序，或通过行级错误报告验证 TOML 语法 → TOML 格式化工具
2
如果你需要将 TOML 配置文件转换为 JSON，用于需要 JSON 输入的 API、脚本或工具 → TOML 转 JSON 工具
3
如果你需要将 JSON 文档转换为 TOML 格式，用于以 TOML 为配置标准的项目 → JSON 转 TOML 工具

对于日常 TOML 工作，TOML 格式化工具可在一步内完成格式化和验证——粘贴你的 TOML，它要么产生整洁的输出，要么精确告诉你语法错误所在。当需要在 TOML 和 JSON 之间桥接时，TOML 转 JSON 工具可保留所有 TOML 数据类型，包括日期时间和嵌套表。反向转换（JSON 转 TOML）请使用 JSON 分类中的 JSON 转 TOML 工具。如果你在调试解析失败的配置，建议从 TOML 格式化工具入手：其错误信息包含行号和预期词素描述，比大多数应用层 TOML 解析器的报错更为具体。

常见问题

TOML 与 YAML 有什么区别？

TOML 使用显式的方括号语法表示表，不依赖缩进来表示结构。YAML 使用缩进来定义层级，因此对空白错误非常敏感——一个错位的空格就可能完全改变解析后的结构。TOML 还拥有原生日期/时间类型，并禁止重复键；而 YAML 在同一键出现两次时会静默使用最后一个值。TOML 通常更适合应用配置，而 YAML 在 Kubernetes 清单和 CI/CD 流水线定义中更为常见，因其多文档支持和锚点/别名功能在这些场景下更有优势。

TOML 与 JSON 有什么区别？

JSON 是为机器间通信设计的数据交换格式。TOML 是为人类读写而设计的配置格式。TOML 支持注释（以 # 开头的行）、原生日期时间类型、多行字符串，以及可减少嵌套深度的表。JSON 不支持注释，没有日期类型，且需要用花括号显式表示嵌套。JSON 适合 API 负载和数据存储；TOML 适合人工手动编辑的配置文件。

TOML 能表示所有 JSON 数据结构吗？

TOML 可以表示大多数 JSON 结构，但存在一些边界情况。TOML 不支持 null 值——没有与 JSON null 等效的 TOML 表示。TOML 的键必须是字符串，这与 JSON 对象键一致。在 v0.5 中 TOML 数组被限制为同构类型，但 TOML v1.0 允许混合类型数组。深度嵌套的 JSON 对象在 TOML 中可能变得冗长，因为每一层嵌套都需要单独的表头。

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

Rust 的 Cargo 构建系统使用 Cargo.toml 作为包清单。Python 通过 PEP 518（2016 年）和 PEP 621（2020 年）将 pyproject.toml 确立为标准构建配置文件。静态站点生成器 Hugo 默认使用 TOML 进行站点配置。InfluxDB 使用 TOML 进行服务器配置。Go 模块系统曾考虑过 TOML，但最终选择了自有格式；不过许多 Go 项目仍通过 BurntSushi/toml 和 pelletier/go-toml 等库在应用层使用 TOML。

TOML 如何处理注释？

TOML 支持整行注释和行尾注释，使用 # 字符。从 # 到行尾的所有内容都会被解析器忽略。注释不能出现在多行基本字符串或多行字面量字符串内部。将 TOML 转换为 JSON 时，注释会被丢弃，因为 JSON 没有注释语法。这意味着 TOML 经过 JSON 再转回 TOML 的往返操作后，原始文件中的所有注释都会丢失。

TOML 中的表数组是什么？

表数组使用 [[双括号]] 语法定义具有相同表结构的重复条目。例如，[[servers]] 出现两次会创建一个包含两个服务器对象的数组。在 JSON 中，这映射为一个对象数组。表数组常用于依赖项列表、服务器定义或插件配置，其中每个条目具有相同的键集合。

TOML 对空白敏感吗？

TOML 不对缩进敏感。缩进纯粹是装饰性的，不影响解析。但 TOML 要求用换行符分隔键值对——不能将两个键值对写在同一行（内联表内部除外）。内联表必须写在单行内，不能包含换行符。这一设计避免了 YAML 文件中常见的基于缩进的错误。

TOML 日期时间值转换为 JSON 时会发生什么？

JSON 没有原生日期时间类型，因此 TOML 日期时间会被转换为 ISO 8601 字符串。带时区偏移的日期时间（如 2024-01-15T09:30:00Z）在字符串表示中保留时区偏移。本地日期时间、本地日期和本地时间分别序列化为不含时区信息的字符串。这种转换在信息上是无损的——原始值可以从字符串中解析还原，但 JSON 的消费方必须知道将这些字符串视为日期而非任意文本。