TOML 与 JSON 互转指南

TOML 简介

TOML（Tom's Obvious Minimal Language）是一种专为配置文件设计的格式，由 GitHub 联合创始人 Tom Preston-Werner 创建。它的目标是：

• 人类可读，语义明确
• 能无歧义地映射为哈希表
• 比 YAML 更简单，比 JSON 更友好

基本语法

title = "TOML 示例"

[owner]
name = "张三"
email = "zhang@example.com"

[database]
host = "127.0.0.1"
port = 5432
enabled = true

TOML vs JSON vs YAML 对比

特性	TOML	JSON	YAML
注释	支持 #	不支持	支持 #
日期类型	原生支持	不支持	不支持
多行字符串	支持	不支持	支持
复杂性	低	中	高
解析歧义	无	无	有
主要用途	配置文件	数据交换	配置文件

使用 TOML↔JSON工具 进行转换

步骤一：选择转换方向

打开 TOML↔JSON工具，选择「TOML → JSON」或「JSON → TOML」。

步骤二：输入数据

将 TOML 或 JSON 内容粘贴到输入区域。支持直接上传文件。

步骤三：转换

点击转换按钮，结果即时显示在输出区域。

步骤四：复制或下载

一键复制转换结果，或下载为对应格式的文件。

TOML 转 JSON 的映射规则

基本类型

string = "hello"
integer = 42
float = 3.14
boolean = true

转为 JSON：

{
  "string": "hello",
  "integer": 42,
  "float": 3.14,
  "boolean": true
}

表（Table）→ 对象

[server]
host = "localhost"
port = 8080

转为 JSON：

{
  "server": {
    "host": "localhost",
    "port": 8080
  }
}

数组

ports = [8000, 8001, 8002]

日期时间

TOML 原生支持日期类型，转为 JSON 时会变为字符串：

created = 2026-06-01T10:00:00Z

→ "created": "2026-06-01T10:00:00Z"

JSON 转 TOML 的注意事项

• JSON 中的 null 在 TOML 中没有对应类型，转换时需特殊处理
• JSON 数组中的混合类型在 TOML 中不合法
• JSON 的嵌套对象会转为 TOML 的表（Table）
• 建议转换后检查注释和格式是否满足需求

常见应用场景

Rust 项目：Cargo.toml

[package]
name = "my-app"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = "1.0"
tokio = { version = "1", features = ["full"] }

需要修改依赖版本时，用 TOML↔JSON工具 转为 JSON 程序化处理后再转回。

Python 项目：pyproject.toml

[project]
name = "my-package"
version = "1.0.0"
requires-python = ">=3.8"

[project.dependencies]
requests = "^2.28"
flask = "^2.3"

静态站点配置

Hugo、Zola 等静态站点生成器使用 TOML 作为配置格式，经常需要与 JSON 格式互转。

与其他格式联动

1. TOML ↔ YAML：先用 TOML↔JSON工具 转为 JSON，再用 YAML↔JSON工具 转为 YAML
2. 转换后用 JSON格式化 验证中间结果
3. 建议保留原始 TOML 中的注释，转换后手动补回

常见错误

错误	原因	解决方法
TOML 解析失败	语法错误	检查表头和键值对格式
日期格式异常	时区信息缺失	补充完整的 ISO 8601 格式
null 无法转换	TOML 无 null	用空字符串或删除该字段
内联表格式错误	语法不规范	改用标准表格式

总结

TOML 是现代配置文件的优秀选择，与 JSON 的互转在项目配置管理中非常实用。TOML↔JSON工具 让你快速完成格式转换，配合 YAML↔JSON 工具还能实现三种格式间的自由切换。