Kratos热更新不生效主因是Watch链路中断：Watch()未注册或返回nil、多源配置覆盖、未调用c.Scan()刷新结构体、Sidecar拦截长连接。
热更新不生效，大概率不是配置没改，而是监听链路断在了某个环节——Kratos 的 Watch() 机制依赖完整注册、正确实现和无干扰的运行时环境。
Watch() 方法未被调用或返回空 Watcher
Kratos 在 c.Load() 后才开始调用每个 source 的 Watch()，但若你手动调用 source.Load() 而没走 config.New().Load() 流程，Watch() 根本不会触发。更常见的是：第三方 source（如 Apollo 封装）返回了 nil 或未启动 goroutine 监听变更。
- 检查日志是否输出
watching config source: polaris类提示——没有就说明Watch()没进或提前 panic - 确认 source 实现中
Watch()返回的Watcher不为nil，且其Next()方法能持续阻塞并返回新值 - Polaris 等 gRPC 源需确保
polaris.yaml存在且含有效serverAddresses；Apollo 长轮询源需验证GetConfig()能通，且回调 goroutine 已启动
配置合并覆盖了热更新后的值
多个 source 按添加顺序合并，后加的会覆盖先加的。如果热更新源（如 Polaris）是第一个添加的，而后面又加了 env.NewSource() 或命令行参数，那哪怕 Polaris 推送了新值，也会被环境变量里旧的同名 key 覆盖掉。
- 用
config.WithSource()添加 source 时，把动态源（Polaris/etcd）放在最后——例如：file.NewSource("default.yaml"), env.NewSource(), polarisSource - 不要在
Watch()回调里直接修改结构体字段；应通过c.Scan(&v)重新解析整个配置，否则嵌套字段可能残留旧引用 - 检查
mergo合并策略：默认是覆盖，但若用了WithMergeOptions(mergo.WithAppendSlice)，切片类配置可能不按预期更新
Watcher 事件被丢弃或未触发 Scan()
Kratos 的热更新不是自动重载结构体，而是靠 config 实例内部监听 Watcher.Next() 并触发 reader.Merge()，最终需要用户显式调用 c.Scan() 才能刷新到 Go 结构体。很多项目只监听了变更，却忘了这一步。
- 必须在初始化 config 后，启动一个 goroutine 持续调用
c.Watch()（注意：这是config.Config的方法，不是 source 的） - 典型写法：
go func() { for range c.Watch() { if err := c.Scan(&bc); err != nil { log.Warnf("scan config failed: %v", err) } } }() - 若使用
kratos-bootstrap，它已内置该逻辑；但手写启动流程时极易遗漏——这也是开发环境看似生效、生产环境失效的高频原因
Sidecar 或代理拦截了配置长连接
在 Istio 等服务网格环境中，Polaris/Apollo 的 gRPC 或 HTTP 长轮询连接可能被 Sidecar 误判为普通业务流量而劫持、超时或重置，导致 Watch 连接频繁断开且无法自动重连。
- 检查客户端日志是否有
connection reset、context deadline exceeded或stream closed - Polaris 源需确认
polaris-go版本 ≥ v1.7.0，该版本修复了 gRPC 连接保活问题；Apollo 源需确保长轮询间隔，避开 Istio 默认的 30s 连接空闲超时 - 在 Kubernetes 中，为配置中心客户端 Pod 添加注解：
traffic.sidecar.istio.io/includeOutboundIPRanges: "0.0.0.0/0"，绕过 outbound 流量劫持
真正卡住热更新的，往往不是「怎么写 Watch」，而是「谁在消费 Watch 事件」「谁在决定用哪个值」「谁在切断底层连接」——这三个角色任何一个掉线，更新就静默失败。
