Gin 配置热加载需 Viper + Consul KV 配合，必须用 viper.WatchRemoteConfig 并手动 Unmarshal；WatchConfig 仅支持本地文件，Consul 需显式导入驱动、正确协议格式及 YAML 格式 value。
Gin 本身不处理配置热加载，必须靠 Viper + Consul KV 配合实现；直接在 Gin 启动后调用 viper.WatchConfig 是无效的——它只监听本地文件，对 Consul 完全无感。
Consul KV 热加载必须用 viper.WatchRemoteConfig
很多人卡在“配置改了但 viper.Get("xxx") 还是旧值”，根本原因是误用了 viper.WatchConfig。这个函数只 watch 本地路径（如 config.yaml），和 Consul 没有任何关系。
-
viper.WatchRemoteConfig才是正确入口，但它不会自动触发Unmarshal，必须手动在回调里调用viper.Unmarshal(&cfg) - 调用
WatchRemoteConfig前，必须先成功执行viper.ReadRemoteConfig()，否则会 panic：remote config not loaded - Consul 驱动需显式导入：
import _ "github.com/spf13/viper/remote"（viper 默认不带 Consul 支持） - Consul 地址格式必须是
consul://127.0.0.1:8500，不能漏掉consul://协议前缀，否则报错unsupported protocol scheme "consul"
Consul KV 路径与数据格式有硬性要求
Consul 的 KV 存储不是任意写入就能被 Viper 解析的。Viper 要求你存进去的是完整、合法的 YAML 字符串，且 key 必须对应整个配置结构的根路径。
- 推荐路径格式：
/gin/config/dev（环境隔离）、/gin/config/common（公共配置） - value 必须是 YAML 格式字符串，比如：
port: 8080\ndb:\n host: localhost，不能是 JSON 或纯文本 - 如果 value 是 JSON，Viper 不会报错但解析失败，
viper.Get("port")返回 nil 或零值 - Viper 不支持嵌套目录自动合并，
/gin/config/dev/db和/gin/config/dev/port是两个独立 key，Viper 不会把它们拼成结构体
热更新回调里必须重新 Unmarshal，不能只靠 Get
Viper 的远程热加载机制是“事件驱动 + 手动同步”。Watch 触发后，Viper 只拉取新 raw data，不会自动覆盖内存中已解析的结构体字段。
- 必须在
viper.OnRemoteConfigChange回调里显式调用viper.Unmarshal(&cfg)，否则业务代码读到的永远是启动时的快照 - 不要在回调里做耗时操作（如 DB 重连、HTTP client 重建），建议用 channel 或 goroutine 异步通知业务层
- 如果结构体字段类型变更（比如
int改成string），Viper Unmarshal 可能静默失败，建议加日志：if err := viper.Unmarshal(&cfg); err != nil { log.Printf("unmarshal failed: %v", err) }
最容易被忽略的一点：Consul KV 的 Watch 依赖长连接，而 Viper 的 WatchRemoteConfig 并不处理网络中断后的自动重连。一旦 consul agent 重启或网络抖动，watch 就会断开且不再恢复——你得自己封装一层带重试的 watcher，或者改用 consul api client 直接监听 KV 变更再手动触发 viper.ReadRemoteConfig。
