“Config File Not Found”主因是Viper默认只查当前目录下的config或config.toml，不自动识别app.toml等自定义名；须显式调用viper.SetConfigFile("./conf/app.toml")并紧接viper.SetConfigType("toml")，或用viper.SetConfigName("app")+viper.AddConfigPath("./conf")且文件名必须为app.toml。
viper.ReadInConfig() 报 “Config File Not Found”？不是路径错了，是它根本没打算猜你用的什么格式或文件名——必须显式告诉它。
为什么 viper.ReadInConfig() 总找不到 app.toml
默认行为极其保守：viper 只在工作目录下找 config（无后缀）或 config.toml，其他名字一律忽略。哪怕你写了 viper.SetConfigName("app")，它也不会去加载 app.toml。
- 正确做法一：用
viper.SetConfigFile("./conf/app.toml")，然后**必须紧跟着**调用viper.SetConfigType("toml")，再执行viper.ReadInConfig() - 正确做法二：用
viper.SetConfigName("app")+viper.AddConfigPath("./conf")，此时它会自动尝试app.toml、app.yaml等，但前提是文件名**恰好带 .toml 后缀** - 调试技巧：加一句
viper.Debug()，它会打印当前注册的搜索路径、已识别的配置源和类型，一眼看出是否加载了目标文件
burntsushi/toml 解析后字段全是零值？检查三件事
这是最常被忽略的硬性约束：Go 的反射看不见小写字母开头的字段，toml 库也就没法赋值。
- 结构体字段必须首字母大写（
Host string✅，host string❌） - TOML 键名默认按小写匹配，
Host string对应 TOML 中的host = "127.0.0.1"；如果 TOML 写的是HOST = "127.0.0.1"，就得加 tag：Host string `toml:"HOST"` - 嵌套表（如
[database]）必须对应嵌套 struct，不能用map[string]interface{}混着来；否则解析成功但字段仍为零值
想取 servers.0.name？别这么干
TOML 解析器不支持索引路径，viper.Get("servers.0.name") 或 viper.GetStringSlice("servers.name") 永远返回空或 panic。
立即学习“go语言免费学习笔记（深入）”；
- 安全做法：先用
viper.Get("servers")拿到整个 slice，断言为[]interface{}，再逐个遍历并转成map[string]interface{} - 更推荐：定义结构体 +
viper.Unmarshal(&conf)，比如type Server struct { Name string `toml:"name"` }，这样类型安全、错误明确、IDE 可跳转 - 注意：点号路径只适用于扁平嵌套（
database.host✅），不适用于数组索引（servers.0.name❌）或深层动态 key（如datatitle.users."12345".prop1）
环境变量覆盖失效？两个 replacer 缺一不可
DATABASE_HOST=localhost 无法覆盖 database.host，不是变量没生效，是映射规则没配对。
- 必须提前调用
viper.SetEnvPrefix("APP")，这样APP_DATABASE_HOST才能对应到database.host - 必须提前调用
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))，否则它会去找DATABASE.HOST（shell 不允许该变量名） - 这两句都必须放在
viper.AutomaticEnv()和viper.ReadInConfig()之前，顺序错就等于没设 - 关键限制：环境变量只对配置文件中**已声明的 key** 生效；如果
config.toml根本没写database这一级，APP_DATABASE_HOST再怎么设也无效
嵌套动态表（比如 [datatitle.users."12345"]）这类结构，struct 绑定天然不支持，得切到 map[string]map[string]interface{} 或用 pelletier/go-toml/v2 的 Tree 接口手动导航——这不是疏忽，是 TOML 规范本身对“动态 key”的设计取舍。
