burntsushi/toml 是当前最稳定、广泛采用的 Go TOML 解析库，因标准库不支持 TOML；其解析快、结构体标签兼容性好、错误提示清晰，虽已归档但仍维护。
为什么用
而不是标准库
Go 标准库不支持 TOML，必须依赖第三方。目前最稳定、被广泛采用的是
（虽已归档，但仍在维护且无严重 bug）。它解析快、结构体标签兼容性好，且错误提示相对清晰。别碰
的 v3+（API 不兼容旧项目），除非你明确要新特性。
解析失败的常见原因
多数报错不是语法问题，而是结构体定义和 TOML 字段不匹配。典型现象：
或静默丢字段。
字段名首字母小写 → 不会被导出 →
无法写入/读取，必须大写
没加
标签，但 TOML 键名含下划线或大小写不一致（如
对应结构体字段
，不加 tag 就会忽略）
TOML 中是数组，结构体里却定义成单个值（或反之），比如
对应
而非
嵌套表（
）必须对应切片，不是单个 struct；而
才对应单个 struct
如何安全地读取配置文件并处理缺失字段
别直接
+
后就开跑。缺字段、类型错、路径不存在都会让程序 panic 或行为异常。
先检查文件是否存在且可读：
，避免空字节切片传给
用指针接收结构体，便于检测零值字段（比如
没写时默认为 0，但 0 可能是合法值，建议加
或用
）
对必填字段，在解析后手动校验：比如
避免全局变量存配置，封装成函数返回结构体，方便测试和复用
示例片段：
立即学习
“
go语言免费学习笔记（深入）
”；
嵌套数组和 inline table 的写法差异
TOML 里
和
完全不同，结构体定义稍有偏差就会解析为空。
→ 必须对应
，每个
是一个数组元素
→ 是嵌套 inline table，结构体得写成
（单个表）→ 对应
，不是切片
如果 TOML 里写了
但 Go 里定义成
，解析不会报错，但
字段始终是零值
最容易被忽略的是：TOML 数组项里允许省略重复 key（如多个
共享
），但 Go 结构体字段不能“继承”，每个 struct 实例都得完整承载自己那一块。
burntsushi/tomlburntsushi/tomlgo-tomltoml.Unmarshaltoml: cannot decode TOML value into *structtomltoml:"xxx"db_portDbPortservers = ["a", "b"]Servers stringServers []string[[servers]][server]os.ReadFiletoml.Unmarshalos.Stat("config.toml")UnmarshalPort int `toml:"port"`omitempty*intif c.Database.URL == "" { return errors.New("missing database.url") }type Config struct {
Server struct {
Port int `toml:"port"`
} `toml:"server"`
Database struct {
URL string `toml:"url"`
} `toml:"database"`
}
data, _ := os.ReadFile("config.toml")
var cfg Config
if err := toml.Unmarshal(data, &cfg); err != nil {
log.Fatal(err) // 别忽略 err
}
[[section]][section][[servers]]Servers []Server `toml:"servers"`[[servers]][servers.common]Servers struct { Common struct{...} } `toml:"servers"`[servers]Servers Server `toml:"servers"`[[servers]]Servers ServerServers[[deploy]]region = "us"