viper.SetConfigName()必须动态拼接，不能写死；正确做法是viper.SetConfigName("config-" + os.Getenv("ENV"))，并配合AddConfigPath("./configs")、SetConfigType("yaml")，且需在ReadInConfig前完成。
viper.SetConfigName() 必须动态拼接，不能写死
配置加载失败最常见的原因是 viper.SetConfigName() 用了固定字符串，比如 "config-prod"。viper 不会自动根据 ENV=dev 去补全文件名，它只认你明确 set 的名字。
正确做法是在调用 viper.ReadInConfig() 前，用环境变量拼出完整配置名：
-
viper.SetConfigName("config-" + os.Getenv("ENV"))—— 注意ENV要提前设好，推荐小写值（dev/prod） - 必须搭配
viper.AddConfigPath("./configs")，且该路径下真实存在对应文件（如./configs/config-dev.yaml） - 若路径不存在或权限不足，
viper.ReadInConfig()可能静默失败，建议启动时加os.Stat()校验
viper.AutomaticEnv() 不生效？检查 SetEnvKeyReplacer 和前缀
viper.AutomaticEnv() 默认只做全字符串匹配，不会自动把点号转下划线。比如你想读 server.port，它会去找名为 SERVER.PORT 的环境变量，但系统里实际是 SERVER_PORT。
必须显式配置映射规则：
立即学习“go语言免费学习笔记（深入）”；
-
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))—— 把结构体字段中的点号替换成下划线 -
viper.SetEnvPrefix("app")—— 这样app.server.port就对应APP_SERVER_PORT - 这两步必须在
viper.AutomaticEnv()之前调用，顺序错就无效 - 如果某个 key 需要特殊映射（如
PGHOST→db.host），用viper.BindEnv("db.host", "PGHOST")显式绑定
嵌套结构体 unmarshal 后字段为空？yaml tag 缺失或不匹配
viper 不会推导字段名，也不做命名风格转换。它只依赖 struct 字段上的 yaml:"xxx" tag，且严格区分大小写、完全匹配。
常见错误示例：
- YAML 里写的是
database-host: localhost，但 struct 字段是DatabaseHost string却没加yaml:"database-host" - YAML 是
log_level: debug，struct 字段写了LogLevel string `yaml:"logLevel"`（驼峰写法错） - 字段首字母小写（如
host string），Go 反射无法导出，viper 根本看不到
务必确保：字段首字母大写 + 显式 yaml:"xxx" tag + tag 值与 YAML 键完全一致（含连字符/下划线）。
多个环境配置共用 base 时，别靠 ReadInConfig 多次加载
有人试图先 ReadInConfig() 加载 config-base.yaml，再加载 config-prod.yaml 想 merge，这会导致覆盖逻辑失控——viper 不保证合并顺序，且重复调用会污染内部状态。
安全做法是拆分 + 显式合并：
- 基础配置单独存为
config-base.yaml，环境特有配置存为config-dev.yaml等 - 先用
viper.MergeConfigFile("config-base.yaml")合并 base - 再用
viper.MergeConfigFile("config-" + env + ".yaml")合并环境专属部分 - 所有
MergeConfigFile()调用后，再统一viper.Unmarshal(&cfg)
生产环境禁用 viper.WatchConfig() —— 热重载可能触发 panic，尤其在并发读取时。配置变更应走滚动重启而非运行时 reload。
