Consul 远程配置必须用 viper.WatchRemoteConfig 且需在 ReadRemoteConfig 成功后调用，否则 panic；其回调中须手动 Unmarshal；Consul key 必须为完整 YAML 字符串，路径不能扁平化；加载顺序决定优先级，本地配置应最后 Merge；ACL token 需提前设置；Gin 启动前应通过 channel 等待首次远程配置就绪。
Consul 远程配置必须用 viper.WatchRemoteConfig，不是 viper.WatchConfig
很多人误以为 viper.WatchConfig 能监听 Consul，其实它只监听本地文件变化。远程热加载必须走 viper.WatchRemoteConfig，且必须在 viper.ReadRemoteConfig() 成功之后调用，否则会 panic：remote config not loaded。
常见错误现象：viper.Get("database.url") 始终返回旧值，日志里也没有 “config changed” 输出；排查发现根本没调用 WatchRemoteConfig，或者调用顺序写反了（比如先 Watch 再 Read）。
-
viper.WatchRemoteConfig不会自动触发Unmarshal，必须手动在OnRemoteConfigChange回调里执行viper.Unmarshal(&cfg) - Consul 驱动依赖
github.com/hashicorp/consul/api，v1.19+ 版本不兼容老版viper/remote，容易报错：unsupported protocol scheme "consul" - Consul 中的 key 值（如
gin/config/dev）对应 value 必须是完整 YAML 字符串，不能是 JSON、纯文本或嵌套结构
本地配置与 Consul 远程配置怎么按优先级合并
Viper 默认支持多源配置叠加，但顺序决定覆盖关系：后加载的配置项会覆盖先加载的同名字段。要实现「本地开发覆盖 > Consul 环境配置 > default.yaml」，必须严格控制加载顺序。
- 先
viper.SetConfigName("default")+viper.AddConfigPath("config/")+viper.ReadInConfig() - 再根据
os.Getenv("APP_ENV")加载dev.yaml或production.yaml（注意：用viper.MergeConfig，不是ReadInConfig，避免重置已加载源） - 最后调用
viper.AddRemoteProvider("consul", "127.0.0.1:8500", "gin/config/"+env)+viper.ReadRemoteConfig() - 本地
local.yaml（.gitignore）应放在最后加载，用viper.MergeConfig注入，确保最高优先级
Consul key 路径和数据格式必须匹配 Viper 解析逻辑
Viper 从 Consul 拉取的是 raw bytes，它不会自动识别 key 层级。比如你存的是 /gin/config/dev，value 是 database:\n url: "mysql://..."，那 viper.GetString("database.url") 才能取到值；如果 value 是 JSON 格式或没有缩进的 YAML，Viper 会解析失败，viper.Get 返回 nil。
- Consul 中的 key 必须是完整路径，不要用目录式嵌套（如
/gin/config/dev/database/url），Viper 不支持这种“扁平 key”映射 - 推荐统一用 YAML 格式，避免空格/缩进错误；可用
yamllint验证本地dev.yaml再同步到 Consul - Consul 的 ACL token 若启用，需通过
viper.Set("consul.token", "...")提前设置，否则ReadRemoteConfig会 403
Gin 启动时如何安全等待远程配置就绪
Consul 配置加载是异步的，viper.ReadRemoteConfig() 返回不代表数据已 ready，尤其配合 WatchRemoteConfig 时，首次拉取可能有延迟。直接启动 Gin 服务可能导致路由初始化时读不到 viper.GetString("server.port")。
- 启动前加简单阻塞等待：用
time.AfterFunc(2 * time.Second, func(){...})不可靠，应改用 channel + context 超时控制 - 更稳妥的做法是在
viper.OnRemoteConfigChange第一次回调里 close 一个readyCh chan struct{}，Ginr.Run()放在select { case 之后 - 若 Consul 不可用，建议 fallback 到本地
fallback.yaml，用viper.SetConfigName("fallback")+viper.ReadInConfig()保底，避免启动失败
实际项目中，最容易被忽略的是 Unmarshal 必须手动触发 —— 即使 Watch 成功、回调也进了，只要没在 OnRemoteConfigChange 里跑一遍 viper.Unmarshal(&cfg)，你的结构体字段就还是旧值。这个点不检查日志、不打断点几乎没法发现。
