etcd.clientv3.put 写入失败主因是 client 未连上 etcd 或 context 被取消；需检查 endpoints、使用带超时 context、显式判断 err；读取应据场景选 withserializable() 或默认 linearizable；watch 需 goroutine 消费、处理重连；client 必须显式 close。
etcd.Clientv3.Put 写入配置时为什么没生效
写不进去，大概率是 client 没连上 etcd 或 context 被提前取消。etcd v3 的 Put 是异步提交、强一致写入，但不会自动重试失败，也不会抛出连接异常——它只返回 *clientv3.PutResponse 和可能的 error，而这个 error 往往是 context.DeadlineExceeded 或 rpc error: code = Unavailable。
- 检查 client 初始化是否传了正确的 endpoints，比如
[]string{"http://127.0.0.1:2379"}，注意不是https（除非启用了 TLS） - 务必用带超时的 context：不要用
context.Background()直接调Put，改用ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) - 必须显式检查返回的
err：即使resp不为 nil，err != nil就代表写入失败 - etcd 默认不允许多级路径自动创建（不像 Redis），但
Put本身不要求父路径存在，这点不用额外处理
读取配置时 Get 返回空值或旧值
常见于没设 WithSerializable() 或误用了 watch 机制。etcd 的读默认是线性一致性（linearizable）读，但如果你在高并发场景下频繁 Get，又没加 WithSerializable()，可能被路由到非 leader 节点并返回过期数据（尤其在跨机房部署时）。
- 普通配置读取建议加
clientv3.WithSerializable()：它允许从任意节点读，性能更好，且对配置类场景足够可靠 - 如果需要绝对最新值（比如开关控制），去掉
WithSerializable()，依赖默认的 linearizable 读（会转发到 leader） - 注意
Get返回的*clientv3.GetResponse中，Kvs是切片：key 不存在时Kvs为空，别直接取Kvs[0] - 不要把
Get结果缓存在本地变量后长期复用——etcd 不推变更，得自己轮询或用 watch
watch 配置变更却收不到事件
watch 不是“订阅”，而是长连接流式响应；收不到更新，通常卡在初始化阶段或被中间件拦截。etcd 的 Watch 接口返回一个 clientv3.WatchChan，本质是 chan clientv3.WatchResponse，但它不会主动启动连接——你得用 goroutine 消费，否则 channel 堵塞会导致后续事件丢弃。
- watch 启动后，必须立刻起 goroutine 持续读
watchChan，例如：go func() { for wr := range watchChan { /* 处理 */ } }() - watch 默认从当前 revision 开始监听，如果配置已在之前被修改，你需要先
Get一次拿到最新 revision，再用clientv3.WithRev(rev)启动 watch - HTTP 代理或 Kubernetes Service 可能重置长连接，建议在 watch err 回调里做自动重连（检查
wr.Err()是否非空） - 避免对高频变更 key（如计数器）用 watch，etcd 对 watch 流量有限制，容易触发 server 端限流
Go 程序退出前没关闭 etcd client 导致 panic
clientv3.Client 是重量级对象，内部持有 gRPC 连接池和 goroutine。如果程序 exit 前不调 cli.Close()，gRPC 会试图在 shutdown 阶段发请求，导致 panic: send on closed channel 或日志刷屏 transport is closing。
立即学习“go语言免费学习笔记（深入）”；
- 所有通过
clientv3.New(...)创建的 client，必须配对调用defer cli.Close()（或在明确生命周期结束处调用） - 在 main 函数里用
signal.Notify捕获os.Interrupt后，先 close client 再 exit，否则 SIGTERM 可能来不及清理 - 不要在多个 goroutine 里共用同一个 client 并发调
Close()—— 它不是幂等的，重复 close 会 panic - 如果用 wire/dig 等 DI 框架管理 client，确保 Close 被注入 shutdown hook，而不是靠 defer
etcd 的配置同步看似简单，但 client 生命周期、watch 消费模型、读一致性级别这三点，几乎覆盖了 80% 的线上问题。细节都在 error 判断和 context 控制里，不是贴个示例代码就能跑通的。
