最稳妥的Go项目配置方案是结构体绑定+多环境文件分离+显式校验；viper因隐式加载、优先级模糊、类型不安全等问题不宜默认使用。
Go 项目里所谓“全局系统配置”，不是靠 var 包级变量硬编码，也不是靠 init() 里读文件完事——真正优雅的管理，是让配置可验证、可覆盖、可调试，且不污染业务逻辑。
viper.UnmarshalExact 替代 viper.Unmarshal
用 viper.Unmarshal 解析结构体时，字段缺失、类型错配、多余字段全被静默吞掉。比如配置里漏了 timeout，结构体字段仍是 0；又或者写了 max-connections: 100，但 struct tag 写成 mapstructure:"max_connections"（下划线 vs 连字符），值就进不去。
- 必须用
viper.UnmarshalExact，它会在字段名或类型不匹配时直接 panic，CI 阶段就能暴露问题 - 所有嵌套字段都得显式加
mapstructuretag，哪怕和字段名完全一致，例如Host string `mapstructure:"host"` - 连字符键名（如
max-connections）必须严格按配置文件里的写法匹配 tag，不能自动转驼峰或下划线
GO_ENV 驱动配置文件名，不靠 if 判断环境
别在业务代码里写 if env == "prod" { loadProdConfig() }。viper 不支持运行时切换配置源，这种写法会让初始化逻辑散落各处，测试难 mock，IDE 跳转失效。
- 在
main()最开头读一次os.Getenv("GO_ENV")，只读一次，避免多次调用开销 - 用它拼出配置名：
viper.SetConfigName("config-" + os.Getenv("GO_ENV"))，配合viper.AddConfigPath("./configs")和viper.SetConfigType("yaml") -
viper.ReadInConfig()必须在这三步之后调用，否则报Config File Not Found或Unsupported Config Type - 文件结构建议：./configs/config-dev.yaml、./configs/config-prod.yaml，不推荐 config.common.yaml + config.dev.yaml 合并——viper 的
ReadInConfig不做 merge，强行多读会覆盖而非叠加
环境变量绑定需显式处理点号层级
viper.AutomaticEnv() 默认把 server.port 映射到 SERVER_PORT，但实际环境变量名通常是 SERVER_PORT，不是 SERVER.PORT。如果你没设替换规则，viper.GetString("server.port") 就永远拿不到值。
立即学习“go语言免费学习笔记（深入）”；
- 必须加
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))，把点号转下划线 - 如果某些字段需要特殊映射（比如环境变量叫
REDIS_URL，但配置项是cache.url），用viper.BindEnv("cache.url", "REDIS_URL") -
AutomaticEnv()必须在ReadInConfig()之前调用，否则无效
生产环境禁用 WatchConfig
viper.WatchConfig() 看似方便热重载，但在生产中极易引发竞态：配置刚改完，goroutine 正在解析，结构体字段可能处于中间状态；更糟的是，如果新配置格式错误或字段类型不兼容，服务可能 panic 退出。
- 开发阶段可用，但上线前务必注释掉
WatchConfig相关代码 - 生产环境应依赖进程重启（如 systemd reload、K8s rolling update）来加载新配置，保证原子性和可回滚性
- 若真需动态生效，应封装为独立的 reload API，并做完整校验 + 原子赋值，而不是依赖 viper 的底层 watch 机制
最常被忽略的一点：viper 初始化顺序不能错——AddConfigPath、SetConfigName、SetConfigType、AutomaticEnv、BindEnv、ReadInConfig，每一步的位置都影响最终行为。少一步或顺序颠倒，轻则 fallback 到默认值，重则 panic 或静默失败。
