viper.WatchConfig()仅触发回调，不自动重载配置；必须在OnConfigChange回调中依次调用ReadInConfig()和Unmarshal()刷新内部缓存与结构体，否则viper.Get()始终返回旧值，且需注意路径匹配、原子替换及组件主动响应。
热更新配置不是开个 WatchConfig 就自动生效的——漏掉 ReadInConfig 或 Unmarshal，改了文件也白改。
WatchConfig 回调里必须重载配置
很多人以为调了 viper.WatchConfig() 就万事大吉，结果改完 config.yaml 后 viper.GetInt("server.port") 还是旧值。根本原因是：WatchConfig 只负责监听 fsnotify 事件，它不读文件、不解析、不刷新内部缓存。
- 回调函数第一行必须手动调
viper.ReadInConfig()，否则viper.AllSettings()和所有Get*方法仍返回旧数据 - 如果用了结构体映射（比如
type Config struct { Server struct{ Port int } }），紧接着必须调viper.Unmarshal(&cfg)；只调ReadInConfig不够，结构体字段不会自动更新 - 别在回调里写
cfg.Port = viper.GetInt("server.port")这种手动赋值——会绕过mapstructuretag、默认值、嵌套结构解析，且无法保证并发安全
SetConfigFile 必须显式指定完整路径
常见现象：“改了配置没反应，控制台也没报错”。大概率是监听路径和实际加载路径不一致。
- 错误写法：
viper.AddConfigPath("./configs"); viper.SetConfigName("app"); viper.SetConfigType("yaml")→WatchConfig默认监听工作目录，不是./configs - 正确写法：
viper.SetConfigFile("./configs/app.yaml")，再调viper.WatchConfig()；viper 会基于这个绝对或相对路径自动绑定 inotify 监听 - 编辑器保存常先写临时文件再
rename，macOS 和某些容器环境（如 overlayfs 挂载）对 rename 事件支持弱，建议开发期加日志：viper.OnConfigChange(func(e fsnotify.Event) { log.Printf("config event: %+v", e) })
并发读配置必须原子切换
多个 goroutine 同时读配置时，直接修改全局结构体字段（如 globalCfg.Server.Port = newPort）会导致读取到中间状态。
- 推荐做法：在
OnConfigChange回调中新建配置实例，完成Unmarshal后，用原子指针替换（atomic.StorePointer）或互斥锁保护的指针赋值 - 避免用
sync.Map存配置项——它不解决结构体字段更新的原子性，且增加间接层 - 如果用 Gin 中间件读配置，确保中间件内访问的是最新指针值，而不是初始化时捕获的闭包变量
最易被忽略的是：热更新后，Gin 的 gin.Engine 实例本身不感知配置变更，比如你改了 server.read_timeout，得自己触发 engine.MaxMultipartMemory 或超时逻辑重置；Viper 管不到框架运行时行为，它只管“数据怎么来”。
