Gin 应用线上用 Consul 做配置中心时，核心是启动早期完成 Consul 远程配置初始化：先 import 相应驱动，再 viper.ReadRemoteConfig() 成功后立即调用 WatchRemoteConfig，并在 Gin 启动前注册 OnRemoteConfigChange 回调手动 Unmarshal 结构体，且远程 YAML key 必须匹配结构体字段名。
线上用 Consul 做配置中心时，Gin 应用打包部署的核心不是“把配置打进二进制”，而是确保启动时能连上 Consul 并正确加载远程配置；否则 viper.Get("xxx") 拿到的永远是空值或默认值。
Consul 远程配置必须在 main 启动早期完成初始化
很多人把 viper.WatchRemoteConfig 放在路由注册之后、router.Run() 之前，结果服务起来了但配置没生效——因为 Watch 必须在 viper.ReadRemoteConfig() 成功后立刻调用，且整个流程得在 Gin 启动前收尾。
-
viper.ReadRemoteConfig()失败会 panic，必须用defer recover()或显式检查 err - etcd 需提前
import _ "github.com/spf13/viper/remote"注册驱动，Consul 则依赖github.com/hashicorp/consul/apiv1.19+（低版本报unsupported protocol scheme "consul"） - 远程 key 的 value 必须是完整 YAML 字符串（比如
/gin/config/prod存的是server:\n port: 8081\nlog_level: debug），不能是 JSON 或纯文本
Docker 打包时不要 COPY 配置文件，但要注入 Consul 地址
本地开发可能用 viper.SetConfigFile("config.yaml")，但线上必须禁用——远程配置和本地文件共存时，viper 优先级混乱，viper.Get() 行为不可预测。
- Dockerfile 中删掉所有
COPY *.yaml或ADD config/相关指令 - 用环境变量传 Consul 地址：
CONSUL_ADDR=consul-server:8500，代码里用viper.AddRemoteProvider("consul", os.Getenv("CONSUL_ADDR"), "/gin/config/$ENV") - 镜像里不带任何配置内容，靠启动时拉取 + 热监听保证一致性
线上发布配置的三步操作流
改配置 ≠ 重启服务，但必须触发 Consul KV 更新 + 确认回调执行。常见错误是改了 KV 却没看到日志输出 config changed，本质是没注册回调或 Unmarshal 漏了。
- 在 Consul UI 或 CLI 执行写入：
consul kv put gin/config/prod 'server:\n port: 8082' - 确保代码中已设置
viper.OnRemoteConfigChange(func(e fsnotify.Event) { viper.Unmarshal(&cfg) })—— 注意：viper 不会自动 Unmarshal，这行必须写 - 观察服务日志是否打印
Received remote config change event，再查viper.Get("server.port")是否已更新
最容易被忽略的是：每次 Consul 配置变更后，viper.Unmarshal(&cfg) 必须手动调用，且 &cfg 是你定义的结构体指针；如果结构体字段名和 YAML key 不匹配（比如用了 json:"port" 但 YAML 是 server_port），值就进不去，还不会报错。
