Python配置文件格式怎么选：JSON、YAML、TOML与INI对比

一、四种配置格式的语法特征与结构映射

配置文件的本质是将磁盘上的静态文本映射为 Python 内存中的数据结构（通常是字典、列表及基本数据类型）。这四种主流格式在设计哲学、数据类型系统以及对注释的支持上存在本质差异。

• INI (Initialization)：起源于 Windows 早期的简单文本配置。采用节（Section）、键（Key）、值（Value）三层平面模型。其主要限制在于所有值被解析时默认都是纯字符串，不支持数组与多级嵌套，没有严格的国际标准规范。
• JSON (JavaScript Object Notation)：Web 领域的数据交换通用标准。数据格式高度标准化，强类型定义（字符串、数字、布尔、空值、数组、对象）。其致命弱点在于官方规范严禁包含注释，且对尾随逗号零容忍，作为人工频繁修改的配置文件体验较差。
• YAML (YAML Ain't Markup Language)：高度面向人类可读性的数据序列化格式。广泛应用于 Kubernetes、Docker Compose 和 GitHub Actions。依靠空白缩进表达层次，支持复杂的字典、列表和对象锚点引用，但语法解析规则极为庞杂。
• TOML (Tom's Obvious, Minimal Language)：专为配置文件设计的清晰强类型语言。它结合了 INI 的区块清晰感与 JSON 的类型严谨性，拥有明确的标量、数组、表格（Table）和行内表格语法，目前已被 PEP 518 / PEP 621 选定为 Python 官方包构建的配置标准（pyproject.toml）。

二、Python 中的解析生态与代码实操

在实际工程中，选择何种配置格式直接影响项目的依赖链。下图展示了 Python 读取与写出四种格式文件的模块调用链路：

1. INI：内置标准库 configparser

Python 的 configparser 支持读取与写入 INI 文件。由于 INI 内部无数据类型概念，读取数字或布尔值时必须显式调用转换方法。

import configparser

config = configparser.ConfigParser()
config.read("config.ini", encoding="utf-8")

# 读取字符串
host = config.get("database", "host", fallback="localhost")
# 显式转换为整型
port = config.getint("database", "port", fallback=5432)
# 显式转换为布尔型（能自动识别 'yes', 'true', '1', 'on' 等）
is_enabled = config.getboolean("database", "enabled", fallback=False)

2. JSON：内置标准库 json

JSON 的解析速度快且开箱即用，但在作为配置文件时无法添加说明性注释。

import json

# 读取配置
with open("config.json", "r", encoding="utf-8") as f:
    config = json.load(f)

db_port = config["database"]["port"]

# 写出配置（保持格式化与中文可读）
with open("config.json", "w", encoding="utf-8") as f:
    json.dump(config, f, indent=2, ensure_ascii=False)

3. YAML：第三方库 PyYAML

由于 Python 标准库未内置 YAML 解析器，需先安装 pip install pyyaml。在加载外部 YAML 文件时，务必使用 safe_load 防止反序列化漏洞。

import yaml

with open("config.yaml", "r", encoding="utf-8") as f:
    # 严禁使用 yaml.load(f, Loader=yaml.Loader)，存在任意代码执行风险
    config = yaml.safe_load(f)

db_port = config["database"]["port"]

4. TOML：标准库 tomllib（Python 3.11+）

从 Python 3.11 起，官方引入了内置的只读模块 tomllib。需要注意该模块仅接收二进制流模式打开的文件：

import sys

if sys.version_info >= (3, 11):
    import tomllib
else:
    # Python 3.10 及以下需安装三方库: pip install tomli
    import tomli as tomllib

with open("config.toml", "rb") as f:
    config = tomllib.load(f)

# 直接解析为标准的强类型字典
db_port = config["database"]["port"]
db_enabled = config["database"]["enabled"]

三、选型决策指南：五步确定最佳格式

不同项目的团队构成、部署方式和配置生命周期各不相同。通过以下五步决策流程，可以快速定位最适合当前业务的格式。

1. 步骤一：评估数据层级结构。如果配置项极少，仅有几十个互不嵌套的平面开关或键值，且不需要布尔、浮点等类型校验，直接使用内置的 INI 是最轻量的做法。若包含列表或字典嵌套，立即排除 INI。
2. 步骤二：评估人工编辑需求与注释依赖。若配置由代码自动生成，主要供服务间通过 HTTP/RPC 交互读取，优先选择 JSON；若配置需交由运维、测试或开发者手动调整，必须包含字段释义注释，必须放弃 JSON。
3. 步骤三：评估生态工具链的集成度。如果项目属于 DevOps 基础设施（如自动化部署脚本、Docker 编排、Kubernetes 自定义资源清单），采用 YAML 可以与云原生生态保持无缝一致。
4. 步骤四：评估运行时依赖约束与 Python 版本。如果运行环境限定在干净的 Python 3.11+ 标准库，且不希望在 requirements.txt 中引入外部 wheel 包，选择 TOML（内置 tomllib）或 JSON。
5. 步骤五：评估安全性与防错成本。YAML 在解析未加引号的字符串时可能产生意料之外的类型转换；而 TOML 具有清晰的引号规则与强类型标记，能有效避免因拼写或缩进导致的线上故障。

四、避坑指南：各格式常见陷阱

在实际生产环境中，盲目套用格式往往会踩入语法或解析器的边界陷阱：

1. YAML 的挪威问题（The Norway Problem）

在 YAML 1.1 规范中，未加双引号的 NO、OFF、YES、ON 都会被解析器自动转为布尔值 False 或 True。

# 陷阱示例：本意是国家代码列表
countries:
  - US
  - GB
  - NO  # 致命陷阱：PyYAML 会将其解析为布尔值 False，而非字符串 "NO"

防范措施：在 YAML 中书写所有字符串值（尤其是简短缩写、版本号如 version: "3.10"）时，强制使用双引号包裹。

2. INI 的类型推导与多节同名覆盖

由于 INI 默认没有数据类型，config['section']['port'] 获取到的一律是 str。如果不经转换直接用于网络监听，会触发 TypeError: an integer is required。同时，INI 默认在相同 Section 下出现同名 Key 时会以后者静默覆盖前者，排查较为隐蔽。

3. TOML 的深层嵌套冗余

TOML 的优势在于 1 至 3 层的扁平与浅层表格。当层级超过 4 层以上时，TOML 需要书写类似 [services.web.backend.database.pool] 的冗长表头，或者使用紧凑的行内表格（Inline Table），但行内表格内部禁止换行，维护性会随之下降。

五、综合选型矩阵与总结

为了直观对比四种格式在工程实践中的全方位表现，下表与总结卡片归纳了各格式的核心指标：

在当今 Python 生态下，如果你正在启动一个新的 Python 项目并需要为应用提供外部配置文件，优先考虑 TOML。它在严谨的数据类型与友好的阅读编辑体验之间找到了最佳平衡，并且能够天然融入现代 Python 打包与工具链标准。