TOML、JSON、YAML、INI 配置文件格式总结

本文总结了 TOML 的含义，并对 TOML、JSON、YAML、INI 这几种常见配置/数据文件格式进行对比，帮助理解它们的相似处、区别和适用场景。

1. TOML 是什么？

TOML 是一种配置文件格式，文件后缀通常是：

text 复制代码

.toml

它的全称是：

text 复制代码

Tom's Obvious, Minimal Language

可以翻译为：

Tom 的直观、极简语言

这里的 Tom 指 TOML 的作者；Obvious, Minimal Language 表示它的设计目标是：

单词	含义	解释
Obvious	直观	人一眼能看懂配置内容
Minimal	极简	语法尽量简单，不搞复杂规则
Language	语言	一种用于表达配置的文本格式

所以 TOML 的核心思想是：

让配置文件既适合人手动编辑，也适合程序读取。

例如 Codex 的配置文件：

bash 复制代码

~/.codex/config.toml

就是一个 TOML 文件。

2. TOML 文件主要用来做什么？

TOML 通常用于软件配置，例如：

toml 复制代码

model = "gpt-5.4"
model_reasoning_effort = "high"

含义是：

text 复制代码

model 这个配置项的值是 "gpt-5.4"
model_reasoning_effort 这个配置项的值是 "high"

常见使用场景包括：

text 复制代码

Python 项目配置：pyproject.toml
Rust 项目配置：Cargo.toml
Codex 配置：~/.codex/config.toml
工具/服务配置文件
Agent / MCP 工具配置

3. TOML 基本语法

3.1 键值对

toml 复制代码

model = "gpt-5.4"
enabled = true
timeout = 30

写法	类型	含义
`"gpt-5.4"`	字符串	文本内容
`true` / `false`	布尔值	开启或关闭
`30`	数字	数值配置

3.2 表 / 配置分组

TOML 用方括号表示配置分组：

toml 复制代码

[projects."/workspace"]
trust_level = "trusted"

可以理解为：

text 复制代码

projects 下面有一个 "/workspace" 项目配置
这个项目的 trust_level 是 trusted

对应 JSON 结构大致是：

json 复制代码

{
  "projects": {
    "/workspace": {
      "trust_level": "trusted"
    }
  }
}

3.3 数组

TOML 使用方括号表示数组：

toml 复制代码

args = ["-y", "@upstash/context7-mcp"]
env_vars = ["CONTEXT7_API_KEY"]

类似 Python 里的列表：

python 复制代码

["-y", "@upstash/context7-mcp"]

3.4 注释

TOML 使用 # 写注释：

toml 复制代码

# 这是注释，不会被程序读取
model = "gpt-5.4"

4. Codex MCP 配置中的 TOML 示例

在 Codex 中，一个 MCP Server 可以这样配置：

toml 复制代码

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["CONTEXT7_API_KEY"]
enabled = true

含义是：

text 复制代码

配置一个名为 context7 的 MCP server
启动命令是 npx
启动参数是 ["-y", "@upstash/context7-mcp"]
把 CONTEXT7_API_KEY 环境变量传给它
启用这个 MCP server

如果配置 arxiv MCP，可以类似这样写：

toml 复制代码

[mcp_servers.arxiv-mcp-server]
command = "npx"
args = ["-y", "@langgpt/arxiv-mcp-server@latest"]
env_vars = ["SILICONFLOW_API_KEY"]
enabled = true

[mcp_servers.arxiv-mcp-server.env]
WORK_DIR = "/workspace/arxiv-mcp-server"

5. TOML 编辑时的常见注意事项

5.1 不要重复定义同一个表

错误示例：

toml 复制代码

[mcp_servers.context7]
command = "npx"

[mcp_servers.context7]
enabled = true

这是错误的，因为 [mcp_servers.context7] 出现了两次。

正确写法：

toml 复制代码

[mcp_servers.context7]
command = "npx"
enabled = true

5.2 字符串要加引号

正确：

toml 复制代码

model = "gpt-5.4"

错误：

toml 复制代码

model = gpt-5.4

5.3 数组要用方括号

正确：

toml 复制代码

args = ["-y", "@upstash/context7-mcp"]

6. JSON、YAML、INI、TOML 的相似处

这几种格式本质上都属于：

用来保存配置数据或结构化数据的文本格式。

它们经常用于：

text 复制代码

软件配置
项目配置
工具参数
服务启动配置
环境配置
API 配置
MCP / Agent 配置

它们都可以表达类似的信息，例如：

text 复制代码

模型名称
是否启用某个功能
路径
端口
参数列表
环境变量
嵌套配置

例如，要表达下面这组信息：

text 复制代码

model = gpt-5.4
enabled = true
args = ["-y", "context7"]

可以分别用 JSON、YAML、INI、TOML 表示。

7. JSON

7.1 JSON 是什么？

JSON 全称是：

text 复制代码

JavaScript Object Notation

它最初来自 JavaScript，但现在已经成为非常通用的数据交换格式。

示例：

json 复制代码

{
  "model": "gpt-5.4",
  "enabled": true,
  "args": ["-y", "@upstash/context7-mcp"]
}

7.2 JSON 的特点

JSON 更适合：

text 复制代码

程序之间传输数据
API 返回结果
Web 前后端通信
机器读取

优点：

text 复制代码

标准化程度高
几乎所有编程语言都支持
结构严谨
适合机器解析

缺点：

text 复制代码

不能写注释
括号、引号、逗号比较多
人工手动编辑配置不够舒服
最后一个元素不能多写逗号

8. YAML

8.1 YAML 是什么？

YAML 是一种常用于配置文件的格式，尤其常见于 DevOps 和云原生场景。

典型场景包括：

text 复制代码

Docker Compose
Kubernetes
GitHub Actions
Ansible
CI/CD 配置

示例：

yaml 复制代码

model: gpt-5.4
enabled: true
args:
  - -y
  - "@upstash/context7-mcp"

8.2 YAML 的特点

YAML 更适合：

text 复制代码

复杂配置
多层级配置
DevOps / 云原生配置
CI/CD 工作流配置

优点：

text 复制代码

可读性强
支持注释
比 JSON 少很多括号
适合写复杂层级结构

缺点：

text 复制代码

非常依赖缩进
缩进错误容易导致配置错误
语法规则比看起来复杂
字符串、布尔值、数字的解析有时容易混淆

例如：

yaml 复制代码

enabled: true

和：

yaml 复制代码

enabled: "true"

含义可能不同：前者是布尔值，后者是字符串。

9. INI

9.1 INI 是什么？

INI 是一种很早期、很简单的配置文件格式，Windows 和很多传统软件都使用过。

示例：

ini 复制代码

model = gpt-5.4
enabled = true

[context7]
command = npx

9.2 INI 的特点

INI 更适合：

text 复制代码

简单配置
传统软件配置
没有复杂嵌套的场景

优点：

text 复制代码

极其简单
人很容易读
适合简单 key-value 配置

缺点：

text 复制代码

标准不够统一
不擅长表达数组、对象和复杂嵌套
不同程序对 INI 的解析规则可能不同

例如表达数组时，INI 没有统一标准：

ini 复制代码

args = -y,@upstash/context7-mcp

这就需要程序自己决定如何解析。

10. TOML

10.1 TOML 的定位

TOML 可以理解为介于 INI 和 YAML 之间：

text 复制代码

比 INI 表达能力更强
比 YAML 更简单、更不容易因为缩进出错
比 JSON 更适合人手写配置

示例：

toml 复制代码

model = "gpt-5.4"
enabled = true
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7]
command = "npx"
enabled = true

10.2 TOML 的特点

TOML 更适合：

text 复制代码

项目配置
工具配置
人工维护的配置文件
需要清晰数据类型的配置

典型例子：

text 复制代码

Cargo.toml          Rust 项目配置
pyproject.toml      Python 项目配置
config.toml         Codex 配置

优点：

text 复制代码

比 JSON 更适合人工编辑
比 YAML 更不容易因为缩进出错
比 INI 更能表达数组、布尔值、数字、嵌套结构
支持注释
类型比较明确

缺点：

text 复制代码

表达特别复杂的数据结构时不如 YAML 灵活
table 重复定义容易报错
语法比 INI 稍复杂

11. 四种格式对比表

格式	全称	主要用途	优点	缺点	适合场景
JSON	JavaScript Object Notation	数据交换、API	标准化强，机器友好，语言支持广泛	不能写注释，人工编辑麻烦	API、Web、程序间数据传输
YAML	YAML Ain't Markup Language	复杂配置、DevOps	可读性强，支持注释，适合复杂层级	缩进敏感，规则复杂，容易踩坑	Kubernetes、Docker Compose、CI/CD
INI	Initialization File	简单配置	极简、容易读写	标准不统一，不适合复杂结构	传统软件、简单配置
TOML	Tom's Obvious, Minimal Language	项目/工具配置	清晰、支持注释、类型明确，适合手写	复杂结构能力中等，重复表会报错	Codex、Python、Rust、工具配置

12. 同一个 MCP 配置的四种写法对比

下面用同一个 MCP server 配置作为例子，对比四种格式。

12.1 JSON

json 复制代码

{
  "mcp_servers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "enabled": true
    }
  }
}

特点：结构严谨，但括号和引号多。

12.2 YAML

yaml 复制代码

mcp_servers:
  context7:
    command: npx
    args:
      - -y
      - "@upstash/context7-mcp"
    enabled: true

特点：看起来简洁，但高度依赖缩进。

12.3 INI

ini 复制代码

[mcp_servers.context7]
command = npx
args = -y,@upstash/context7-mcp
enabled = true

特点：简单，但数组表达不标准，依赖程序自己解析。

12.4 TOML

toml 复制代码

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true

特点：清晰、支持数组和布尔值，适合人工手动维护配置。

13. 最简单的记忆方式

text 复制代码

JSON：给机器看的数据格式，常用于 API 和数据交换。
YAML：给复杂系统写配置，常用于 DevOps，但缩进容易出错。
INI：最简单的老式配置格式，适合简单 key-value。
TOML：给人手写、给程序读取的现代配置格式。

对于 Codex MCP 场景，可以这样理解：

text 复制代码

Codex 使用 TOML，是因为它既需要人能手动编辑，
又需要表达 MCP server、启动命令、参数、环境变量、项目路径等结构。

14. 选择建议

你的需求	推荐格式
API 返回数据、程序间传输	JSON
Kubernetes、Docker、CI/CD 等复杂配置	YAML
非常简单的软件配置	INI
项目配置、工具配置、Codex MCP 配置	TOML

15. 总结

TOML、JSON、YAML、INI 都是文本格式，都可以用来描述配置或结构化数据。

它们的核心区别在于：

text 复制代码

JSON 更偏机器读写；
YAML 更偏复杂配置；
INI 更偏简单配置；
TOML 更偏现代项目配置和人工可维护配置。

在你的 Codex 场景中，~/.codex/config.toml 用 TOML 是比较合适的，因为它既清晰，又能表达 MCP 工具所需的复杂配置，例如：

text 复制代码

工具名称
启动命令
启动参数
是否启用
环境变量
工作目录
项目路径信任配置