Viper 不自动多环境发现，需手动拼接配置名并调用 SetConfigName；嵌套结构体字段必须加 mapstructure tag；环境变量覆盖需 SetEnvKeyReplacer、SetEnvPrefix 和 AutomaticEnv 配合；Unmarshal 前必须先 ReadInConfig；测试需调用 Reset() 避免状态污染。
必须手动拼接配置文件名，Viper 不会自动根据 ENV 变量找 config.dev.yaml
SetConfigName 必须动态调用，不能写死
常见错误是把 viper.SetConfigName("config") 写成固定值，结果无论 ENV=prod 还是 ENV=dev，它都只去找 config.yaml。Viper 没有“自动多环境发现”能力。
- 正确做法：在
viper.ReadInConfig()前，用环境变量拼出完整名字，例如viper.SetConfigName("config." + os.Getenv("APP_ENV")) - 确保
APP_ENV已设置（推荐小写：dev/prod），且对应文件真实存在（如./config.dev.yaml） - 如果配置路径不一致（比如 dev 文件在
./configs/，prod 在/etc/myapp/），需提前调用viper.AddConfigPath("./configs")或viper.AddConfigPath("/etc/myapp/") - 建议启动时加
os.Stat()校验文件是否存在，避免静默失败
嵌套结构体字段必须带 mapstructure tag
YAML 里写 database: { host: "127.0.0.1", port: 3306 }，但 viper.GetString("database.host") 返回空？不是文件没读到，而是反射没匹配上字段。
- 顶层字段可省略 tag，但只要出现嵌套（哪怕只有一层），所有子字段都必须显式声明
mapstructure:"xxx" - 例如：
Host string `mapstructure:"host"`、Port int `mapstructure:"port"`，连字符字段如max-connections也得写成`mapstructure:"max-connections"` - 字段首字母必须大写（否则 Go 反射不可见），且
mapstructure值要和 YAML 键完全一致（大小写、连字符、下划线都不能错） - 调试时先跑
viper.AllKeys()，确认解析出的 key 列表是否含database.host，再查结构体定义
环境变量覆盖需 SetEnvKeyReplacer + AutomaticEnv 配合
设了 APP_DATABASE_HOST=10.0.0.1，但 viper.GetString("database.host") 还是返回配置文件里的值？因为默认情况下，APP_DATABASE_HOST 不会映射到 database.host。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 必须在
viper.ReadInConfig()前调用：viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))（把点转下划线） - 同时调用：
viper.SetEnvPrefix("APP")和viper.AutomaticEnv()，三者缺一不可 - 顺序无关，但必须都在
ReadInConfig()之前；否则环境变量注册失败，后续Get*调用完全无视它们 - 若只想覆盖个别敏感字段（如密码），用
viper.BindEnv("database.password", "APP_DATABASE_PASSWORD")更精确
Unmarshal 前必须 ReadInConfig，且结构体字段不能写初始化值
结构体定义里写 Port int = 8080 是非法语法；更隐蔽的问题是：调了 viper.ReadInConfig() 后直接 viper.GetInt("server.port") 能拿到值，但 viper.Unmarshal(&cfg) 后 cfg.Server.Port 还是 0。
-
viper.ReadInConfig()只把内容加载进内部 map，不会自动赋值给结构体字段 - 必须紧接着调
viper.Unmarshal(&cfg)才完成绑定；两个调用之间不能插其他逻辑（如改默认值） - 结构体字段不能写初始化值（Go 语法不允许），默认值要用
viper.SetDefault("server.port", 8080)设置 - 测试时务必调
viper.Reset()，否则单例状态残留会导致用例间污染
最容易被忽略的是：环境变量映射规则和 ReadInConfig() 的执行顺序——错一次，整个覆盖链就断了，而且不报错，只默默用文件里的旧值。
