应使用MQTTnet库而非手动解析协议，因其能正确处理CONNECT报文、心跳及会话恢复；ConnectAsync失败需先验证TCP连通性，注册ApplicationMessageReceivedHandler必须在ConnectAsync前，KeepAlive建议设为30–60秒。
直接用 MQTTnet，别自己解析协议——手动拼 CONNECT 报文、处理心跳、管理会话恢复，99% 的连接失败和消息丢失都源于此。
ConnectAsync 失败但没报具体错误？先查 TCP 层通不通
常见错误现象：Connection closed unexpectedly、Authentication failed、超时无响应，但日志里只看到泛泛的 MqttCommunicationException。
- 用
telnet broker.example.com 1883或nc -zv broker.example.com 1883直接测端口连通性，排除防火墙、NAT、Docker 网络隔离问题 - 如果用的是域名（如
Options.ChannelOptions.RemoteEndpoint设为mqtt.example.com），某些嵌入式设备或受限环境 DNS 解析失败，换成 IP 地址更可靠 - 检查 Broker 是否监听在正确端口：EMQX 默认开 1883（MQTT）和 8084（WebSocket），阿里云 IoT 默认是 1883 或 443（TLS）
- 生产环境务必启用日志：
factory.ConfigureLogger(x => x.WithConsoleFormatter().WithMinLevel(LogLevel.Debug))，能看到实际发出的 CONNECT 报文和返回的 CONNACK 码
订阅后收不到消息？ApplicationMessageReceivedHandler 绑定时机错了
很多人把 client.UseApplicationMessageReceivedHandler 放在 ConnectAsync 之后，但 MQTT 协议允许 Broker 在发送 CONNACK 后立刻推送 QoS 1/2 的离线消息——这些消息会在 handler 绑定前就丢掉。
- 必须在
ConnectAsync调用前注册 handler，顺序不能错 - 订阅多个主题时，用
MqttClientSubscribeOptionsBuilder构建，支持通配符：.WithTopicFilter(f => f.WithTopic("factory/actuator/+/command")) - 若 Broker 启用了遗嘱消息（Will Message），确保
WithWillMessage中的 Topic 和 QoS 与订阅一致，否则可能收不到设备离线通知 - QoS 选择影响行为：
MqttQualityOfServiceLevel.ExactlyOnce触发四次握手，适合关键指令；普通传感器上报用AtLeastOnce更稳妥
硬件设备跑不起来？.NET 版本和 TLS 配置是硬门槛
树莓派、工业网关等边缘设备常跑 .NET 6 或 .NET Framework 4.8，部分旧设备甚至还在用 4.6.1；同时很多公有云 Broker（如 AWS IoT Core、华为云 IoTDA）强制要求 TLS 1.2+ 双向认证。
- 确认
MQTTnet版本兼容性：4.3.1.873 支持 .NET Standard 2.0+，能覆盖 .NET Framework 4.6.1 到 .NET 8 全系列 - 启 TLS 时，
Options.TlsOptions.UseTls必须设为true，且Options.TlsOptions.Certificates必须传入完整证书链（CA + client cert + key），缺一不可 - Windows Server 2012 R2 或旧版 IoT Edge 默认禁用 TLS 1.2，需手动注册表开启，否则
ConnectAsync会静默失败 - 嵌入式设备内存紧张？禁用日志（
ConfigureLogger不调用）并设WithCleanSession(true)减少会话状态开销
最易被忽略的点：KeepAlive 值不是可选项，而是连接存活性的生死线。设成 0 或不设，多数云平台（包括 EMQX 默认配置）会在 90 秒内主动断连；设太长（如 5 分钟），弱网下重连延迟陡增。30–60 秒是硬件设备实测最稳的区间。
