新项目优先选TOML，K8s集成场景必须用YAML，纯API服务或跨语言对接才考虑JSON；TOML与Go结构体映射最自然、支持注释和table分组、不依赖缩进、容错性强，YAML易因缩进和类型解析翻车，JSON缺乏注释且嵌套可读性差。
Go项目该用 JSON、YAML 还是 TOML 做配置文件？直接说结论：新项目优先选 TOML，K8s 集成场景必须用 YAML，纯 API 服务或跨语言对接才考虑 JSON。
为什么 TOML 是 Go 新项目的默认推荐
TOML 在 Go 生态中落地最顺，不是因为它“最新”，而是它和 Go 的结构体映射最自然、容错最强、协作成本最低。
-
github.com/BurntSushi/toml是事实标准库，稳定、无 CGO 依赖、解析快 - 字段名到 key 的映射几乎零心智负担：
Port int `toml:"port"`和 JSON/YAML 写法一致，但不会因缩进或引号出错 - 天然支持注释、table 分组（
[database]）、数组写法简洁：hosts = ["db1", "db2"] - 不强制缩进、不区分空格/Tab、冒号后无需空格——运维改配置时基本不会手抖崩掉服务
- 时间类型原生支持：
started_at = 2026-06-03T07:45:00Z，不用额外转 string 再 parse
YAML 在 Go 里用得最多，但最容易翻车
不是因为 YAML 本身差，而是它的解析器（gopkg.in/yaml.v3）对输入太敏感，而 Go 开发者又常忽略细节。
- 缩进混用（空格 + Tab）会导致
yaml: line X: did not find expected key，错误位置往往和真实问题隔好几行 - 布尔值写成
enabled: yes或debug: on会被自动转成true，但enabled: YES就报错——大小写不统一就挂 - 字符串含冒号又没加引号，比如
dsn: user:pass@tcp(localhost:3306)/db，解析器会把user:pass当成一个 key-value 对 - K8s 配置必须用 YAML，但建议 Go 项目只在
deploy.yaml这类编排文件里用；应用自身配置仍走 TOML，避免环境耦合
JSON 在 Go 配置中其实很鸡肋
它适合做 API 响应体，不适合当项目配置文件——除非你明确需要被前端 JS 直接读取或和非 Go 服务共享同一份配置。
立即学习“go语言免费学习笔记（深入）”；
- 不支持注释，上线后没人敢改
config.json，怕删错逗号导致整个服务起不来 - 嵌套深了根本没法快速定位字段，比如
"database": {"connection": {"pool": {"max": 20}}}，不如 TOML 的[[database.connection.pool]]直观 - 所有字符串都得加双引号，数字不能带前导零（
"port": "08080"是 string，"port": 08080是语法错误），类型边界模糊 - 如果你真要用 JSON，至少加一层校验：用
json.RawMessage延迟解析关键段，或配合gojsonq做字段存在性检查
别忽略环境变量和配置层叠的实际影响
格式只是表象，真正决定配置健壮性的是加载逻辑。TOML/YAML/JSON 文件本身不解决覆盖、优先级、热更新问题。
- 生产环境必须支持环境变量覆盖，例如
DATABASE_URL覆盖config.toml里的database.url，否则容器部署就僵住 - 不要手写多环境配置（
config.dev.toml/config.prod.toml），用os.Getenv("ENV")动态拼路径，或用koanf这类库做 backend 合并 - 配置变更后 reload 不等于热更新：
fsnotify监听文件变化再全量重载，比试图 patch 结构体更安全可靠 - 哪怕选了 TOML，也要在 CI 流程里加一步
tomljson config.toml >/dev/null校验语法，防低级错误漏到线上
