最常卡在连接建立失败或上下文超时，根源是Endpoint地址、TLS配置、ctx超时三者未与etcd实际参数对齐；clientv3.New()不拨号，首次RPC才建连，需为Get/Put等操作显式设ctx超时。
Go 用 clientv3 连 etcd，最常卡在连接建立失败或上下文超时，不是代码写错，而是配置没对齐服务端实际状态。
连接时 Endpoint 地址写错或服务未监听 2379 端口
本地开发最常见错误是直接写 "localhost:2379"，但 etcd 实际可能监听 "127.0.0.1:2379" 或绑定到了 0.0.0.0；更常见的是 etcd 根本没启动，或者启动时用了非默认端口（比如 --listen-client-urls=http://0.0.0.0:2380 却没改 client 端口）。
- 先确认 etcd 进程是否运行：
ps aux | grep etcd或systemctl status etcd - 检查监听地址：
lsof -i :2379或netstat -tuln | grep 2379 - 如果 etcd 启动参数含
--advertise-client-urls，客户端Endpoints必须与之匹配，不能只看--listen-client-urls - 容器环境注意网络模式：Docker 默认 bridge 模式下，
localhost指容器内，不是宿主机；应改用宿主机 IP 或host.docker.internal（Mac/Win）或docker network inspect查网关
clientv3.New() 返回 nil 或 panic，DialTimeout 不起作用
clientv3.New() 是同步阻塞调用，它只校验配置结构体合法性，不真正拨号；真正的连接延迟发生在首次 RPC（如 Put 或 Get）时。所以即使 DialTimeout 设为 5 秒，New() 也可能秒返回，但后续操作卡住十几秒才报错。
- 必须在首次业务调用（如
client.Get(ctx, "key")）前，给ctx设好超时，例如context.WithTimeout(context.Background(), 3*time.Second) -
DialTimeout只控制底层 TCP 建连阶段，不包含 TLS 握手、gRPC 初始化等耗时；若启用了 TLS，还要额外预留时间 - 集群多 endpoint 场景下，
clientv3会轮询尝试，某个节点挂了不会立即失败，但总耗时可能叠加 —— 建议把Endpoints控制在 3 个以内，避免无效重试拖慢首请求
证书校验失败导致连接被拒绝（TLS 场景必踩）
生产环境 etcd 几乎都启用 TLS，但 Go 客户端默认不加载系统 CA 或自签名证书，clientv3.New() 会静默忽略证书问题，直到第一次 RPC 才报 rpc error: code = Unavailable desc = connection closed before server preface received 或更模糊的 context deadline exceeded。
立即学习“go语言免费学习笔记（深入）”；
- 显式传入
TLS配置：用embed.FS或os.ReadFile加载ca.crt、cert.pem、key.pem，构造*tls.Config - 禁用证书校验仅限调试：
tls.Config{InsecureSkipVerify: true}，但上线前必须删掉 - 注意证书域名匹配：若 etcd
--advertise-client-urls=https://etcd-cluster.example.com:2379，则证书 Subject Alternative Name（SAN）必须含该域名，不能只靠 IP
忘记 defer client.Close() 导致 goroutine 和连接泄漏
clientv3.Client 内部维护 gRPC 连接池和 watch stream goroutine，不手动 Close() 会导致资源长期驻留，尤其在短命命令行工具或测试中极易复现泄漏。
- 只要
clientv3.New()成功，就必须配对defer client.Close()，哪怕后续操作全失败 - 不要在函数中途 return 前漏掉
Close()；建议统一放在main()或初始化函数末尾 - watch 场景下，
client.Watch()返回的 channel 不会因client.Close()自动关闭，需自行处理接收逻辑退出
真正难排查的永远不是“怎么连”，而是“为什么看起来连上了却读不到数据”——多数时候是 endpoint 地址、TLS 配置、上下文超时三者之一没对齐 etcd 实际运行参数，而不是 clientv3 的 API 用错了。
