Consul客户端连不上本地agent因默认访问http://127.0.0.1:8500但agent未启动或配置不匹配；服务注册后不可发现因健康检查缺失导致状态为critical；服务发现为空因passingOnly未设true、tag匹配错误或stale读取；Watch未Stop引发goroutine泄漏。
Consul客户端初始化为什么连不上本地agent
默认配置下 consul.NewClient 会尝试连接 http://127.0.0.1:8500，但如果你本地没启动 Consul agent，或启用了 ACL、HTTPS、非默认端口，就会报 Get \"http://127.0.0.1:8500/v1/status/leader\": dial tcp 127.0.0.1:8500: connect: connection refused。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 先确认 Consul agent 是否运行：
consul version和curl -s http://localhost:8500/v1/status/leader都得有响应 - 显式传入配置，别依赖默认值：
cfg := consul.DefaultConfig() cfg.Address = "127.0.0.1:8500" // 或 "consul.service:8500"（K8s场景） cfg.Scheme = "http" // 若启用了 TLS，这里要改成 https client, _ := consul.NewClient(cfg)
- 开发时禁用 TLS 验证（仅限本地）：
cfg.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}
注册服务时 HealthCheck 失败导致服务不健康
Consul 默认把未配置健康检查的服务标记为 critical，即使注册成功，consul.Health().Service("myservice", "", true) 也查不到它——因为健康状态不是 passing。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 必须提供至少一个
Check，哪怕只是 TTL 类型：registration := &consul.AgentServiceRegistration{ ID: "myapp-001", Name: "myapp", Address: "10.0.1.100", Port: 8080, Check: &consul.AgentServiceCheck{ TTL: "30s", // 必须定期调用 client.Agent().UpdateTTL(...) }, } - HTTP 类型检查要注意路径和超时：
HTTP: "http://localhost:8080/health"，且确保该端点返回 200；超时默认是 10s，长连接场景建议显式设Timeout: "5s" - 别漏掉
client.Agent().ServiceRegister(...)的错误检查——注册失败不会 panic，但err != nil时服务根本没进目录
服务发现时 GetService 返回空列表但 Consul UI 能看到
常见原因是参数传错：consul.Health().Service() 第二个参数是 tag，不是正则或模糊匹配字段；第三个参数是 passingOnly，默认为 false，但多数人只关心健康实例。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 明确传
passingOnly: true：services, _, err := client.Health().Service("web", "", true, &consul.QueryOptions{AllowStale: false}) - Tag 匹配是精确的，多个 tag 要用逗号分隔字符串，不是数组：
"cache,prod"，不是[]string{"cache", "prod"} - 本地开发时加
AllowStale: false避免读到过期缓存（尤其在单节点 Consul 下，stale 可能返回空） - 注意返回的
services是[]*consul.ServiceEntry，每个 entry 的Service字段才含真实地址和端口，别直接打印services看结构
goroutine 泄漏：忘记关闭 Watch 机制
用 consulapi.NewWatch 或 client.Health().ServiceWatch 启动监听后，如果不显式调用 watch.Stop()，底层 goroutine 和 HTTP 连接会一直挂着，压测时内存持续上涨。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- Watch 必须绑定生命周期管理，比如在 HTTP handler 中启动 watch，也要在
defer或 context cancel 时停掉：w, _ := consulapi.NewWatch(&consulapi.WatchParams{ Type: "service", Service: "db", }) go w.Run(func(idx uint64, val interface{}) { /* 处理变更 */ }) // …… defer w.Stop() // 关键 - 不要在循环里反复 NewWatch —— 每次都新建 goroutine，旧的没关就泄漏了
- 如果只是做一次性查询，别用 Watch，直接调
client.Health().Service()更轻量
Consul 的 Go SDK 行为高度依赖 agent 配置和网络环境，很多“不工作”其实卡在健康检查逻辑或 watch 生命周期上，而不是 API 调用本身。
