mqttnet是c#生态中连接mqtt服务器最可靠的选择，因其完整实现mqtt协议、支持qos、tls、websocket等特性，而m2mqtt等库或手写tcp层易导致连接失败、消息丢失等问题。
MQTTnet 是当前 C# 生态中连接 MQTT 服务器最可靠的选择——别碰 M2Mqtt 或手写 TCP 层，99% 的连接失败、消息丢失、QoS 不生效问题都源于底层协议实现不完整。
ConnectAsync 失败但没报具体错误？先查 TCP 层通不通
常见错误现象：Connection closed unexpectedly、Authentication failed、超时无响应，但日志里只有泛泛的 MqttCommunicationException。
- 用
telnet broker.example.com 1883或nc -zv broker.example.com 1883直接测端口连通性，排除防火墙、Docker 网络隔离、NAT 转发问题 - 如果
Options.ChannelOptions.RemoteEndpoint设的是域名（如mqtt.example.com），某些嵌入式设备或受限环境 DNS 解析会失败，换成 IP 更可靠 - 阿里云 IoT、EMQX Cloud Serverless 等公有云 Broker 默认只开 TLS 端口（如 8883），用 1883 会静默失败；确认 Broker 实际监听端口（EMQX 默认 1883/TCP + 8084/WS + 8883/TLS）
- 生产环境务必启用日志：
factory.ConfigureLogger(x => x.WithConsoleFormatter().WithMinLevel(LogLevel.Debug))，能看到实际发出的 CONNECT 报文和返回的 CONNACK 码
ApplicationMessageReceivedHandler 绑定必须在 ConnectAsync 前
很多人把 client.UseApplicationMessageReceivedHandler 放在 ConnectAsync() 之后，结果订阅后收不到消息。
- MQTT 协议允许 Broker 在发送 CONNACK 后立刻推送 QoS 1/2 的离线消息——这些消息会在 handler 绑定前就丢掉
- 正确顺序：构建 client → 注册
ApplicationMessageReceivedAsync→ 调用ConnectAsync - 订阅操作（
SubscribeAsync）可以放在连接后，但接收回调绑定不能晚于连接 - 若需支持通配符（如
sensor/+/temperature），确保 Broker 开启了通配符订阅权限（部分云服务默认关闭）
KeepAlivePeriod 和 CleanSession 设置不当会导致心跳失效或离线消息堆积
-
KeepAlivePeriod建议设为 30–60 秒；设太短（如 5 秒）会触发 Broker 频繁断连，设太长（>120 秒）可能被 NAT 网关踢掉连接 -
CleanSession = true表示每次连接都是全新会话，Broker 不保留离线消息；设为false时，必须配好ClientId（固定值），否则会话无法恢复 - 嵌入式设备内存紧张？禁用日志（不调用
ConfigureLogger）并设WithCleanSession(true)减少状态开销 - TLS 场景下，
Options.TlsOptions.UseTls必须为true，且Certificates必须传入完整链（CA + client cert + key），缺一不可；Windows Server 2012 R2 等旧系统需手动开启 TLS 1.2 注册表项，否则ConnectAsync静默失败
真正容易被忽略的点是：MQTT 连接不是“建立一次就完事”，而是持续依赖心跳、会话状态、Broker 策略三者协同。哪怕代码逻辑完全正确，一个没开的 TLS 1.2、一个被防火墙截断的 KeepAlive 包、或者一个未清理的旧会话，都足以让消息停在半路。
