推荐使用 github.com/pelletier/go-toml/v2，它支持 toml 1.0 规范，api 清晰、错误提示明确，结构体标签需严格匹配 key（大小写与下划线），解析时必须传指针，不兼容 v1 或 burntsushi/toml。
用 github.com/pelletier/go-toml/v2 解析标准 TOML 文件
Go 官方不内置 TOML 支持，主流选择是 pelletier/go-toml/v2（v2 是当前活跃维护版本）。它支持 TOML 1.0 规范，结构体标签兼容性好，API 清晰。
安装命令：
go get github.com/pelletier/go-toml/v2
典型用法是定义结构体 + 使用 toml.Unmarshal：
假设配置文件 config.toml 内容为：
[database] host = "localhost" port = 5432 ssl = true [features] enable_cache = true timeout_ms = 3000
对应结构体和读取代码：
type Config struct {
Database struct {
Host string `toml:"host"`
Port int `toml:"port"`
SSL bool `toml:"ssl"`
} `toml:"database"`
Features struct {
EnableCache bool `toml:"enable_cache"`
TimeoutMs int `toml:"timeout_ms"`
} `toml:"features"`
}
func main() {
data, _ := os.ReadFile("config.toml")
var cfg Config
if err := toml.Unmarshal(data, &cfg); err != nil {
log.Fatal(err) // 注意：err 可能是语法错误、类型不匹配、字段缺失等
}
fmt.Println(cfg.Database.Host) // "localhost"
}
关键点：
-
toml:标签值必须与 TOML 中的 key 完全一致（包括大小写和下划线） - 嵌套表（如
[database]）对应匿名或具名结构体字段，且需显式指定toml:"xxx" - 未在结构体中声明的 TOML 字段会被静默忽略；反之，结构体字段若未在 TOML 中出现，默认值（零值）会被保留
处理缺失字段或可选配置项
当某些配置项在 TOML 中可能不存在（比如新功能开关尚未上线），直接绑定结构体会导致字段为零值，但你无法区分“用户没配”和“用户配了 false/0”。
解决方式是用指针或 toml.Unmarshaler 接口，更推荐使用指针：
type Config struct {
Database struct {
Host *string `toml:"host"`
Port *int `toml:"port"`
SSL *bool `toml:"ssl"`
} `toml:"database"`
}
此时如果 TOML 中没有 host，cfg.Database.Host 就是 nil，你可以明确判断是否缺失：
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
if cfg.Database.Host == nil {
log.Println("host not set in config")
} else {
log.Printf("host: %s", *cfg.Database.Host)
}
注意：int 和 bool 指针在 JSON 中常见，但在 TOML 中也完全适用；不过所有字段都用指针会增加解引用成本，建议只对真正可选的字段使用。
遇到 toml: cannot load type *struct 错误怎么办
这个错误通常出现在结构体字段类型与 TOML 值类型不匹配时，比如 TOML 写了 port = "5432"（字符串），但结构体字段是 int。
go-toml/v2 默认不做字符串到数字的自动转换，也不会把布尔字符串（"true"）转成 bool。它严格按类型解析。
常见诱因和修复方式：
- TOML 中数字加了引号 → 删掉引号：
port = 5432，不是port = "5432" - 布尔值写成字符串 → 改为裸布尔：
ssl = true，不是ssl = "true" - 想支持字符串形式的数字？得自己实现
UnmarshalTOML方法，或先用map[string]any解析再手动转换 - 字段名拼写错误或大小写不一致（TOML 是大小写敏感的）→ 检查
toml:"xxx"标签是否与文件中 key 完全一致
要不要用 go-toml/v1 或其他库
v1 已归档，不再维护，且 API 不兼容 v2（比如 Decode vs Unmarshal，结构体标签默认行为不同），新项目不要用。
另一个常用库 github.com/BurntSushi/toml 虽稳定，但它只支持 TOML 0.4.0，不支持数组内联表、多重嵌套、日期时间字面量等 1.0 新特性，且已多年无实质更新。
结论很明确：新项目统一用 github.com/pelletier/go-toml/v2，它的错误提示比旧库清晰，对 Unicode 和注释支持更好，而且结构体绑定逻辑更贴近开发者直觉。
唯一容易被忽略的是：v2 的 Unmarshal 不接受 interface{} 类型参数，必须传指针（&cfg），传值会 panic —— 这个细节在快速复制示例时最容易出错。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
