viper.WatchConfig()仅触发回调，不自动更新配置；必须在回调中显式调用ReadInConfig()和Unmarshal()并原子替换配置指针，否则viper.Get()和业务变量始终返回旧值。
viper.WatchConfig() 不会自动更新你的结构体变量，只触发回调
这是最常踩的坑：改完 config.yaml，日志里看到 “config changed”，但 viper.GetInt("port") 还是旧值，业务代码里的 cfg.Port 也纹丝不动。根本原因是 viper.WatchConfig() 只负责监听文件变更并调你的回调函数，它不读文件、不解析、更不会把新值写进你声明的 Go 结构体。
- 回调里必须手动调
viper.ReadInConfig()，否则viper.AllSettings()和viper.Get()仍返回旧缓存 - 紧接着必须调
viper.Unmarshal(&newCfg)，否则你的结构体字段永远卡在初始化那一刻 - 别在回调里写
cfg.Port = viper.GetInt("port")—— 嵌套字段、mapstructuretag、默认值、类型校验全失效 -
viper.SetConfigType("yaml")必须在viper.ReadInConfig()之前设好，否则 YAML 文件按 JSON 解析，静默失败或 panic
用 atomic.Value 原子替换配置指针，别直接赋值结构体
并发场景下，多个 goroutine 同时读配置（比如 HTTP handler、定时任务），如果 reload 时直接写 cfg = newCfg，会出现“半更新”状态：一个 goroutine 读到 cfg.Port == 8080，另一个却读到 cfg.DBURL == "old.example.com"，尤其结构体含指针或嵌套 map 时极易 panic。
- 声明
var globalConf atomic.Value，初始化时globalConf.Store(&defaultCfg) - reload 成功后，构造新实例
newCfg := &Config{}，再globalConf.Store(&newCfg)（注意取地址） - 业务代码统一用
conf := globalConf.Load().(*Config)读取，类型断言不能省 - 避免用
sync.RWMutex包裹整个配置读写 —— 读多写少时，锁竞争比原子操作重得多
fsnotify 监听路径必须精确，别被编辑器临时文件干扰
现象是“改了文件没反应”，控制台无报错。常见根因是监听路径不匹配或事件被误过滤：VS Code、vim 等编辑器保存时，常先写 .config.yaml.swp 或 config.yaml~，再 rename 覆盖原文件。若你监听的是目录 "./config"，收到的是 Create + Remove 事件，不是 Write；若没校验 event.Name，就会尝试解析一个空或损坏的临时文件。
立即学习“go语言免费学习笔记（深入）”；
- 显式调用
watcher.Add("./config.yaml")，不要只加目录 - 在事件处理 goroutine 中，用
filepath.Base(event.Name) == "config.yaml"精确过滤 - 只响应
fsnotify.Write和fsnotify.Chmod（Linux/macOS 编辑保存常用），Create仅在确认是目标文件时才处理 - 收到事件后，先
os.Stat(event.Name)确认文件存在且大小 > 0，再os.ReadFile
容器/K8s 环境下 inotify 耗尽导致 WatchConfig 静默失效
Linux 容器默认 fs.inotify.max_user_watches 极低（常为 8192），fsnotify 监听失败时只报 No space left on device，不是磁盘满，而是内核 inotify 句柄耗尽。现象是配置文件明明改了，但回调从不触发，也没有错误日志。
- Docker 启动容器时必须加参数：
--sysctl fs.inotify.max_user_watches=524288 - K8s 中需在
securityContext.sysctls显式设置，仅调高宿主机无效 - 更稳妥方案：启动前设环境变量
VIPER_CONFIG_WATCH_POLL=true（v1.12+ 支持），启用轮询 fallback - 检查挂载权限：
ls -l /etc/config/app.yaml，确保 Go 进程有读权限（某些镜像 umask 导致文件不可读）
热加载真正的难点不在监听，而在于“新配置是否真正驱动了下游组件”。比如数据库连接池大小变了，得调 db.SetMaxOpenConns()；日志级别变了，得调 zap.AtomicLevel.SetLevel()。这些逻辑不会随 atomic.Value 切换自动生效，必须你在 reload 成功后显式触发 —— 它们才是最容易被忽略的环节。
