什么是 JSON 转 TOML 转换？

JSON 转 TOML 转换是将 JavaScript Object Notation 格式的数据转换为 Tom's Obvious Minimal Language 格式的过程。JSON 使用花括号、方括号和带引号的键来表示结构化数据。TOML 使用扁平的键值语法和节头（称为表），读起来像 INI 文件，但具有严格的类型定义。TOML 专门为配置文件设计，在这类场景中，人类可读性比机器数据交换更为重要。

TOML 已成为 Rust（Cargo.toml）、Python 打包（pyproject.toml）、Hugo 静态站点、Netlify 部署配置以及众多 CLI 工具的默认配置格式。当你的源数据以 JSON 形式存在——来自 API 响应、导出的配置或生成的文件——而目标系统需要 TOML 时，你需要一个能将 JSON 对象映射为 TOML 表、将 JSON 数组映射为 TOML 数组，并准确保留每种数据类型的转换工具。

在线将 JSON 转换为 TOML 是从现有 JSON 数据生成有效 TOML 最快捷的方式。转换会自动处理类型映射：JSON 字符串变为 TOML 字符串，JSON 数字变为 TOML 整数或浮点数，JSON 布尔值直接对应，JSON 对象变为 TOML 表。唯一的例外是 null——TOML 没有 null 类型，因此 null 值会被省略，或根据转换器的处理方式转换为空字符串。

为什么使用这个 JSON 转 TOML 转换器？

配置文件需要 TOML，而 API 和工具输出的是 JSON。这个转换器弥合了两种格式之间的差距，让你无需手动重写即可在二者之间迁移数据。

⚡

即时转换

粘贴 JSON 即可立即获得 TOML 输出。转换随输入实时运行，无需服务器往返，无需上传文件。

🔒

隐私优先处理

所有转换均在浏览器本地进行。JSON 中的配置密钥、API 密钥和数据库凭据永远不会离开你的设备。

🔀

完整结构支持

嵌套对象变为 TOML 表，对象数组变为表数组（[[table]]），混合类型数组也能正确处理。

📋

无需账号

打开页面即可转换。无需注册，无需安装扩展程序，无需 CLI 依赖。支持任何有现代浏览器的设备。

JSON 转 TOML 使用场景

Rust 项目配置

Cargo.toml 定义了 Rust 项目的依赖项、功能特性和构建设置。可将 JSON 依赖列表或生成的配置直接转换为 Cargo.toml 格式。

Python 打包（pyproject.toml）

PEP 518 和 PEP 621 将 pyproject.toml 标准化为 Python 项目的元数据文件。可将现有的 JSON 包元数据转换为所需的 TOML 结构。

静态站点配置

Hugo、Netlify 等静态站点生成器使用 TOML 配置文件。从基于 JSON 的配置迁移或以编程方式生成配置时，可将输出转换为 TOML。

DevOps 与基础设施

Terraform（部分提供商）、Consul 等工具以及各类容器运行时均支持 TOML 配置。可将 JSON 导出的设置转换为 TOML，无需逐一重新输入。

API 响应转配置文件

REST API 返回 JSON。当你需要将这些数据用作 TOML 配置——例如功能开关或环境设置——时，粘贴响应即可获得有效的 TOML。

学习 TOML 语法

TOML 初学者和开发者可以粘贴熟悉的 JSON 结构，查看等价的 TOML 输出，从而快速理解 TOML 的语法规则。

JSON 与 TOML 对比

JSON 和 TOML 在功能上有重叠，但在语法、类型支持和预期用途上存在差异。下表展示了影响转换结果的主要区别。

特性	JSON	TOML
Syntax	Braces, brackets, colons, commas	Key = value, [table], [[array]]
Comments	Not allowed (RFC 8259)	Supported with #
Data types	string, number, boolean, null, object, array	string, integer, float, boolean, datetime, array, table
null support	Native (null)	No null type — omit the key or use empty string
Nested objects	Unlimited nesting depth	Dotted keys or [table.subtable] headers
Arrays of objects	Array of objects with []	[[array-of-tables]] syntax
Readability	Moderate — bracket-heavy at depth	High — flat key-value pairs
Spec	RFC 8259 / ECMA-404	TOML v1.0.0 (toml.io)

TOML 转换注意事项

TOML 有一些与 JSON 不同的规则，会影响转换输出。以下四个问题是最容易引起混淆的地方。

TOML 没有 null 类型

JSON 支持 null 作为一等值。TOML 完全没有 null 类型。转换时，null 值必须被处理——要么完全省略该键，要么使用空字符串，或选择一个占位值。这意味着从 JSON 到 TOML 再转回的往返过程可能无法还原原始的 null 值。

异构数组受限

JSON 数组可以自由混合类型：[1, "two", true]。TOML v1.0.0 要求数组中所有元素类型相同。如果 JSON 中包含混合类型数组，转换器必须将所有元素转为字符串或报错。当源数组包含混合类型时，请检查输出结果。

深层嵌套对象会变得冗长

JSON 通过嵌套花括号自然处理深层嵌套。TOML 使用带点的键或链式 [table.subtable.key] 头，对于深度嵌套结构可能会变得很长。输出是有效的，但不如原始 JSON 紧凑。

键名限制

TOML 裸键只能包含 ASCII 字母、数字、连字符和下划线。JSON 键可以是任意字符串。如果 JSON 键中含有空格、点号或特殊字符，在 TOML 输出中必须对这些键加引号。大多数转换器会自动处理，但如果键中包含特殊字符，请务必核查输出。

代码示例

以编程方式将 JSON 转换为 TOML 在大多数语言中都需要 TOML 序列化库。标准库负责 JSON 解析，TOML 输出则需要专用包。

JavaScript (Node.js)

import { stringify } from '@iarna/toml'

const json = '{"title":"My App","database":{"host":"localhost","port":5432}}'
const obj = JSON.parse(json)
const toml = stringify(obj)
console.log(toml)
// → title = "My App"
// →
// → [database]
// → host = "localhost"
// → port = 5432

Python

import json
import tomli_w  # pip install tomli_w

json_str = '{"title": "My App", "database": {"host": "localhost", "port": 5432}}'
data = json.loads(json_str)
toml_str = tomli_w.dumps(data)
print(toml_str)
# → title = "My App"
# →
# → [database]
# → host = "localhost"
# → port = 5432

package main

import (
    "encoding/json"
    "fmt"
    "github.com/pelletier/go-toml/v2"
)

func main() {
    jsonStr := `{"title":"My App","database":{"host":"localhost","port":5432}}`
    var data map[string]interface{}
    json.Unmarshal([]byte(jsonStr), &data)

    tomlBytes, _ := toml.Marshal(data)
    fmt.Println(string(tomlBytes))
    // → title = 'My App'
    // →
    // → [database]
    // → host = 'localhost'
    // → port = 5432
}

CLI (yj / remarshal)

# Using yj (https://github.com/sclevine/yj)
echo '{"title":"My App","port":3000}' | yj -jt
# → title = "My App"
# → port = 3000

# Using remarshal (pip install remarshal)
echo '{"title":"My App","port":3000}' | remarshal -if json -of toml
# → title = "My App"
# → port = 3000

常见问题

JSON 转 TOML 是无损的吗？

对于大多数数据是无损的。字符串、整数、浮点数、布尔值、对象和数组都有对应的 TOML 类型。有两个例外：null（TOML 没有 null 类型，null 值会被省略或替换）和混合类型数组（TOML 要求数组元素类型统一）。只要 JSON 避开这两种模式，转换就是完全无损的。

JSON 的 null 值在 TOML 中如何处理？

TOML 没有 null 类型。转换器通常会在输出中省略值为 null 的键，因为 TOML 无法表示「键存在但没有值」。部分转换器允许选择使用空字符串代替。如果 null 值在数据中有实际含义，请检查输出结果。

TOML 能表示嵌套的 JSON 对象吗？

可以。JSON 对象变为 TOML 表。例如嵌套对象 {"database": {"host": "localhost"}} 会转换为 [database] 表头，其下有 host = "localhost"。任意嵌套深度均可通过带点的键或嵌套表头来支持。

Rust 和 Python 为什么使用 TOML 而不是 JSON？

TOML 支持注释，这对于记录配置选择至关重要。对于扁平键值设置，TOML 也能生成更简洁的输出，而这类设置在包元数据中占了绝大部分。JSON 禁止注释（RFC 8259），使其难以作为人工编辑的配置格式来维护。

TOML 如何处理日期和时间？

TOML 原生支持日期时间类型：带时区的日期时间（2024-01-15T10:30:00Z）、本地日期时间、本地日期和本地时间。JSON 没有日期类型——日期以字符串形式存储。将 JSON 转换为 TOML 时，类日期字符串除非转换器明确检测并转换 ISO 8601 格式，否则仍保持为字符串。

将密钥和凭据粘贴到此工具中安全吗？

安全。转换完全在浏览器中使用 JavaScript 运行，不向任何服务器发送数据。你可以打开浏览器开发者工具，切换到网络选项卡，确认转换过程中没有任何请求被发出。

输出遵循哪个 TOML 版本？

输出遵循 TOML v1.0.0，该版本于 2021 年 1 月发布，是当前的稳定规范。此版本要求数组类型统一，支持带点的键，并定义了日期时间格式。规范由 toml.io 维护。

JSON 转 TOML