context deadline exceeded 错误主因是客户端初始化时传入的 context 超时时间不足，而非网络或配置错误；需检查 dial 超时与 context 超时匹配，并避免复用已 cancel 的 context。
etcd 客户端初始化失败：context deadline exceeded 是网络还是配置问题？
context.DeadlineExceeded 错误在首次连接 etcd 时高频出现，不是代码写错了，大概率是客户端没等对地方。默认 clientv3.New 不带超时控制，但底层 dial 用的是 grpc.WithTimeout（默认 10 秒），而你传的 context 如果本身只剩 2 秒，就直接爆这个错。
- 检查
etcd地址是否可连：telnet 127.0.0.1:2379或curl -v <a href="https://www.php.cn/link/9ff478a05056d2fe0d7d1e1dd9b35a5f">https://www.php.cn/link/9ff478a05056d2fe0d7d1e1dd9b35a5f</a> - 初始化时显式传入带足够余量的
context，比如context.WithTimeout(context.Background(), 5*time.Second) - 避免复用已 cancel 的
context—— 常见于把 HTTP handler 的r.Context()直接丢给clientv3.New - 若跑在 Docker/K8s，确认服务名解析和端口映射正确，
<a href="https://www.php.cn/link/d9ee56d47bdcadd39f2ec0d61f571cf3">https://www.php.cn/link/d9ee56d47bdcadd39f2ec0d61f571cf3</a>不能靠猜
cli, err := clientv3.New(clientv3.Config{
Endpoints: []string{"http://127.0.0.1:2379"},
DialTimeout: 5 * time.Second,
})监听配置变更时 Watch 一直不触发：为什么 Watch 像挂了？
clientv3.Watch 是长连接 + 流式响应，不是轮询。它“不触发”通常因为三个原因：路径没匹配上、revision 滞后、或 watch channel 被提前关闭。
- 确保监听 key 使用完整路径，比如想监听
/app/database/host，就写cli.Watch(ctx, "/app/database/host")，别漏前导/ - 第一次 Watch 建议加
clientv3.WithPrevKV()，否则改完值你收不到旧值，没法做对比 - 必须持续读取
watchChan，一旦 goroutine 退出或 channel 被 close，watch 就静默断开（不会报错） - 如果 etcd 集群有 leader 切换，watch 可能重连，此时需检查
ev.Events是否为空，避免 panic
从 Etcd 加载配置到 struct：用 json.Unmarshal 还是 mapstructure.Decode？
Etcd 存的是 raw bytes，value 通常是 JSON 字符串。直接 json.Unmarshal 可以，但字段名大小写、嵌套结构、默认值处理会很快变得棘手。
- 优先用
mapstructure.Decode（来自github.com/mitchellh/mapstructure），它支持 tag 映射、零值覆盖、嵌套解码，对配置场景更鲁棒 - 注意
mapstructure默认忽略空字符串和 0 值，如需保留，加DecodeHook处理 - 不要手动拼接 key 路径，封装成函数统一管理，比如
GetConfig(ctx, "database")内部自动补前缀/app/ - 避免每次 HTTP 请求都去
Get一次 —— etcd 读性能 OK，但没必要，配置应缓存在内存里，只在Watch回调里更新
Go Web 服务热更新配置：HTTP handler 里怎么安全替换正在使用的 config 实例？
直接全局变量赋值 config = newConfig 看似简单，但并发下可能让 handler 读到半新半旧的 struct（尤其是含指针或 map 的字段）。
立即学习“go语言免费学习笔记（深入）”；
- 用
sync.RWMutex包一层，读多写少场景下性能损耗极小 - 更稳妥的做法是用
atomic.Value，它保证写入和读取都是原子的，且类型安全：var config atomic.Value config.Store(&Config{Host: "old"}) // 写 cfg := config.Load().(*Config) // 读 - 别在 Watch 回调里做耗时操作（比如 reload DB 连接池），先存进
atomic.Value，再异步通知其他模块 - 如果 config 结构体很大，注意 GC 压力 ——
atomic.Value每次Store都会创建新对象，旧对象得等 GC 回收
配置热更新真正难的不是“怎么换”，而是“换的时候老请求还在用谁”。这个边界得自己划清楚，库不会替你决定。
