Go客户端连不上Pulsar主因是serviceUrl协议头错误或TLS配置不当：明文用pulsar://:6650，TLS用pulsar+ssl://:6651并配TrustCertsFilePath；Consumer收不到消息常因ReceiverQueueSize预取过多或SubscriptionType设错；Send超时多因topic格式非法、broker版本不兼容或大消息未限流；BatchReceivePolicy生效需ReceiveQueueSize足够大。
Go 客户端连不上 Pulsar 服务，十有八九是 serviceUrl 格式或 TLS 配置错了，而不是代码逻辑问题。
为什么 NewClient 一直超时或 panic？
Go 客户端初始化失败最常见原因不是网络不通，而是 URL 协议头写错或端口不匹配。Pulsar 服务默认提供两种协议入口：
-
pulsar://：明文通信，对应 broker 的6650端口（非 TLS） -
pulsar+ssl://：TLS 加密通信，对应6651端口，且必须配置TLSOptions
如果服务启用了 TLS 但你仍用 pulsar://localhost:6650，客户端会卡在连接 handshake 阶段，日志里只显示 context deadline exceeded，不会明确报 TLS 错误。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 先确认服务端配置：查
broker.conf中tlsEnabled=true和brokerServicePortTls=6651是否开启 - 本地测试优先用
pulsar://localhost:6650+ 关闭 TLS 的 broker 启动方式，排除干扰 - 若必须用 TLS，
TLSOptions中的TrustCertsFilePath必须指向 PEM 格式的 CA 证书（不是 .crt 或 .pfx），路径需为绝对路径或相对于可执行文件的相对路径
Consumer 接收不到消息？检查 ReceiverQueueSize 和 SubscriptionType
Go 客户端默认 ReceiverQueueSize=1000，这会导致消费者一启动就预取 1000 条消息到本地内存队列。如果业务处理慢、没及时 Ack，或订阅类型设错，就会出现“明明发了消息却收不到”的假象。
常见错误现象：
- Shared 订阅下，多消费者收不到消息 —— 实际是消息被其他同 subscription 的 consumer 预取走了
- Exclusive 订阅下，重启 consumer 后丢失部分消息 —— 因为旧 consumer 还没 ack，新 consumer 无法接管 backlog
- 设置
ReceiverQueueSize=0但依然收不到 —— 注意：pulsar-client-go 当前版本（v0.13.1）会强制将 ≤0 的值重置为 1000，它不支持真正的 zero-queue 模式（社区 issue 仍在 open）
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 调试阶段把
ReceiverQueueSize设为1，配合consumer.Receive()手动拉取，能最直观看到消息流 - 确认
SubscriptionName在同一集群内全局唯一；重复名称会导致消费位点错乱 - 用
pulsar-admin topics stats查看 topic 的subscriptions字段，核对msgBacklog和unackedMessages数值
Send 报 context deadline exceeded 怎么办？
这个错误表面是超时，根源通常是 broker 拒绝接收或 client 与 broker 版本不兼容。尤其要注意：
- Pulsar Go SDK v0.13.1 默认使用
protov14 协议，若 broker 是 2.9.x 或更老版本，可能不支持某些字段（如SchemaInfo序列化方式），导致 send 请求被静默丢弃 - Producer 创建时未指定
Topic或 topic 名称格式非法（例如漏掉persistent://前缀），broker 会返回 400 但 Go client 封装后统一转成 context timeout - 大消息（>1MB）未开启
MaxPendingMessages或MaxPendingMessagesAcrossPartitions限流，触发 broker 的流控保护
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 发送前用
fmt.Printf("topic: %q", topic)打印 topic 字符串，确保符合persistent://tenant/namespace/topic格式 - 升级 broker 到 3.0+ 或降级 client 到 v0.11.0（适配 2.10.x broker）
- 小流量测试时加
Timeout: 30 * time.Second到ProducerOptions，避免默认 30s 超时掩盖真实问题
BatchReceivePolicy 不生效？优先看 ReceiveQueueSize
Go client 的 BatchReceive 行为受两层队列控制：底层 TCP 连接的 ReceiveQueueSize（消费者本地缓存）和上层 API 的 BatchReceivePolicy。后者只有在前者足够大时才起作用。
例如：设了 MaxNumMessages=10，但 ReceiveQueueSize=5，那每次最多只返回 5 条——因为 client 根本没从 broker 拉够 10 条下来。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
ReceiveQueueSize建议 ≥MaxNumMessages × 2，留出缓冲余量 -
BatchReceivePolicy.Timeout单位是毫秒（time.Millisecond），别误用time.Second导致等待过久 - 收到批量消息后，
MessageID是用"###"分隔的字符串，别直接用strings.Split(msgID, "\n")—— 官方示例明确要求按"###"切分
真正难调的是 receiver queue 和 batch policy 的协同阈值，不是参数本身。线上环境务必用真实吞吐压测，而不是靠单条消息验证逻辑。
