连不上 Broker 首先检查三件事：1. Broker 地址和端口 TCP 是否可达；2. TLS 是否正确配置（仅 ssl:// 前缀无效，需传 tls.Config）；3. 用户名密码是否启用且 Broker 端已授权。
用 paho.mqtt.golang 连不上 Broker？先检查这三件事
连不上基本不是代码写错，而是网络或配置卡在了底层。常见现象是 connection refused、timeout 或静默失败（没报错也没回调）。
-
Broker地址和端口是否可通？用telnet broker.example.com 1883或nc -zv broker.example.com 1883直接测 TCP 连通性，别依赖 Go 程序报错来判断 - 是否用了 TLS？
ssl://前缀只在 URL 字符串里起提示作用，实际要传tls.Config给mqtt.NewClientOptions，否则会 fallback 到明文连接并可能被拒绝 - 用户名密码是否启用？有些 Broker（如 EMQX 默认配置）要求显式开启 auth，光填
SetUsername不够，还得确认 Broker 端用户已添加且权限正确
Connect() 成功但 Subscribe() 没回调？注意 QoS 和 Topic 匹配规则
MQTT 的订阅不是“发个请求就立刻生效”，它有异步确认机制，而且 Topic 过滤严格区分大小写和层级。
-
Subscribe()调用后必须等OnConnect回调里的client.Subscribe(...)执行完成，并监听OnMessage；直接在Connect()后立刻Publish()很可能消息发出去了但没人收 - Topic 中的
+和#是通配符，但 Broker 必须开启通配符支持（例如 Mosquitto 默认关闭allow_anonymous时也禁用通配），test/+/sensor不会匹配test/a/b/sensor - QoS 设置不一致会导致行为差异：QoS 0 不保证送达，QoS 1 可能重复，QoS 2 在 Go 客户端里需要手动处理
OnPublish确认，否则 Broker 会重发
收不到消息？检查 OnMessage 注册时机和 goroutine 安全
OnMessage 回调是在 paho 内部 goroutine 里触发的，如果回调函数里做了阻塞操作（比如同步 HTTP 请求、锁竞争），会拖慢整个消息泵，甚至导致后续消息堆积或断连。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 务必在
mqtt.NewClientOptions里设置SetOnConnectHandler，并在其中调用Subscribe()—— 不要在Connect()返回后“外面”再订，容易错过首次连接窗口 - 不要在
OnMessage里直接修改共享变量而不加锁；更推荐把消息推到一个chan *mqtt.Message，由单独 goroutine 消费 - 确认 Broker 是否真的发了消息：用
mosquitto_sub -h broker.example.com -t 'your/topic' -v交叉验证，排除发送端问题
Disconnect() 不生效？别漏掉 WaitTimeout
调用 client.Disconnect(0) 并不会立即释放连接，它只是发 FIN 包并等待 Broker ACK；如果设为 0，客户端会无限等待，程序 exit 时可能卡住。
立即学习“go语言免费学习笔记（深入）”；
- 生产环境务必用带超时的断开：
client.Disconnect(1000)（单位毫秒），1000ms 是经验值，太短可能丢 ACK，太长影响 graceful shutdown - 如果程序要退出，记得先
Disconnect()，再等几毫秒（比如time.Sleep(10 * time.Millisecond)），否则 runtime 可能直接 kill 掉未完成的 goroutine - 频繁重连场景下，别复用
Client实例 ——paho.mqtt.golang的 client 不是线程安全的，每次新建更稳妥
MQTT 在 Go 里看着简单，但网络抖动、QoS 语义、Broker 配置差异这些细节，往往比代码逻辑本身更耗时间。尤其是通配符订阅失败、消息乱序、断连后自动重连策略这些点，文档很少提，得靠抓包和 Broker 日志交叉看。
