tomllib 是 Python 3.11+ 内置只读 TOML 解析模块，需用 rb 模式打开文件后传入 file object，错误统一抛出 tomllib.TOMLDecodeError。
tomllib 是 Python 3.11+ 的内置模块，无需 pip 安装
Python 3.11 正式将 tomllib 作为标准库引入（PEP 680），它只负责解析（read-only），不提供序列化能力。如果你在 Python 3.11 或更高版本中执行 import tomllib 报错，大概率是环境没切对——检查 python --version 输出是否真为 3.11.x 或以上；旧版本（如 3.10）必须用第三方 tomli 库替代，但接口几乎一致。
基本用法：用 tomllib.load() 读取文件对象
不能直接传路径字符串，必须先打开文件并传入 file object，且推荐用 rb 模式（TOML 规范要求 UTF-8 编码，rb 可避免解码歧义）：
import tomllib
with open("config.toml", "rb") as f:
data = tomllib.load(f)
常见错误包括：
- 用
"r"模式打开 → 可能触发UnicodeDecodeError或静默乱码 - 传入字符串路径（如
tomllib.load("config.toml")）→ 报TypeError: expected bytes-like object, not str - 忘记
with或未关闭文件 → 小文件影响不大，但不符合资源管理习惯
解析失败时的错误类型是 tomllib.TOMLDecodeError
所有语法错误、编码问题、嵌套超限等都会抛出这个明确异常，不是泛化的 ValueError 或 Exception：
立即学习“Python免费学习笔记（深入）”；
try:
with open("bad.toml", "rb") as f:
data = tomllib.load(f)
except tomllib.TOMLDecodeError as e:
print(f"第 {e.lineno} 行，列 {e.colno}：{e.msg}")
注意：e.lineno 和 e.colno 是 1-based（首行首列为 1），和编辑器显示一致；但 e.msg 较简略（如 "Invalid leading character"），复杂问题仍需配合 toml-lint 等工具定位。
与第三方库（如 tomli）的兼容性差异
如果你要兼顾 Python tomli 是最平滑的过渡方案，因为 tomllib 就是基于它实现的。但有两点关键区别：
-
tomllib不支持parse()函数（即不能直接解析字符串）；若需从字符串解析，得先转io.BytesIO(b"...") -
tomllib对浮点数溢出更严格：如inf、nan会直接报TOMLDecodeError，而tomli3.0+ 默认允许（可通过参数关） - 两者都**不支持注释保留**、**不支持写入**，这点容易被忽略——如果项目后期需要生成或修改 TOML，得额外引入
tomlkit或rtoml
真正要注意的是：一旦用了 tomllib，就锁死了最低 Python 版本为 3.11；而很多生产环境还没升级，上线前务必确认解释器版本和部署管道是否同步更新了。
