MQTTnet是C#生态最稳定可靠的MQTT实现，避免手动解析协议出错；需正确配置KeepAlive、TLS、认证及日志，并在ConnectAsync前注册消息处理器，发布时必须await防止阻塞和异常丢失。
用 MQTTnet 而不是自己手写协议解析
MQTT 协议本身有连接、心跳、QoS、遗嘱消息等细节，自己拼包解包极易出错，且难以覆盖断线重连、会话恢复等真实场景。直接用成熟库是唯一靠谱选择，MQTTnet 是目前 C# 生态最稳定、文档最清晰、.NET Standard 2.0+ 全支持的实现。
常见错误现象：Connection closed unexpectedly 或 Authentication failed，往往是因为手动构造 CONNECT 报文时字段顺序/长度/标志位不对，或忽略 KeepAlive 心跳超时设置。
- NuGet 安装：
MQTTnet（注意别装错成旧版MQTTnet.Server或带 .Client 后缀的废弃包） - 必须用
MqttFactory创建客户端实例，不要 newMqttClient—— 否则无法正确管理生命周期和事件 - 连接前务必设置
Options.KeepAlivePeriod（建议 30–60 秒），否则很多物联网平台（如阿里云 IoT、EMQX 默认配置）会主动踢掉无心跳连接 - 若设备需 TLS 双向认证，
Options.TlsOptions.UseTls要设为true，且Options.TlsOptions.Certificates必须传入完整证书链（含 CA + client cert + key）
ConnectAsync 失败时别只看异常类型
ConnectAsync 抛出的 AggregateException 或 MqttCommunicationException 往往掩盖了真实原因。比如网络不通、端口被封、Broker 地址写错，都会统一表现为“连接超时”，但日志里看不到底层 Socket 错误码。
使用场景：调试本地连接测试环境 OK，一上生产就失败；或者在 Docker 容器里跑不通。
- 先用
telnet broker.example.com 1883（或nc -zv）确认 TCP 层通不通，排除防火墙/NAT 问题 - 检查
Options.ChannelOptions.RemoteEndpoint是否用了域名——某些嵌入式设备或受限环境 DNS 解析失败，换成 IP 更可靠 - 如果 Broker 要求用户名密码，
Options.Credentials的Username和Password必须非空且 URL 编码（特别是含/、+、=时），否则认证直接被拒 - 启用 MQTTnet 内置日志：
factory.ConfigureLogger(x => x.WithConsoleFormatter().WithMinLevel(LogLevel.Debug))，能看到实际发送的 CONNECT 报文内容和响应码
订阅后收不到消息？重点查 ApplicationMessageReceivedHandler 绑定时机
很多人把 client.UseApplicationMessageReceivedHandler 放在 ConnectAsync 之后，但没意识到：MQTT 协议允许 Broker 在 CONNECT ACK 后立刻推送 QoS 1/2 的离线消息。如果 handler 没在连接完成前注册，这部分消息就丢了。
性能影响：handler 函数内做耗时操作（如写数据库、调 HTTP API）会导致 MQTTnet 内部消息队列积压，最终触发 FlowControl 限流甚至断连。
- 必须在
client = factory.CreateMqttClient()之后、ConnectAsync之前注册UseApplicationMessageReceivedHandler - handler 回调里不要
await长时间异步操作，应转给后台任务处理（例如Task.Run(() => Process(msg))），并加 try/catch 防止未捕获异常终止整个接收流 - 检查
msg.Topic是否匹配预期——有些平台（如华为云 IoT）会自动加前缀（如$iothub/），而订阅时用的是裸 Topic 名 - QoS 0 消息不保证送达，调试阶段建议订阅时显式指定
QoS = MqttQualityOfServiceLevel.ExactlyOnce，再看是否还丢
发布消息卡住或报 OperationCanceledException
这不是网络问题，而是 PublishAsync 默认使用内部信号量控制并发数（默认 10），当大量快速调用（比如传感器每秒发 50 条）又没 await，就会排队阻塞，最终超时抛 OperationCanceledException。
兼容性影响：.NET 6+ 的 ValueTask 返回值容易让人误以为可以忽略 await，但 MQTTnet 的 PublishAsync 仍是普通 Task，不 await 就等于放任异常吞没。
- 发布前务必
await client.PublishAsync(...)，不要用.Wait()或.Result—— 会死锁 UI 线程或 ASP.NET 同步上下文 - 如需高吞吐，调大
Options.CommunicationTimeout（比如 30 秒）并设置Options.MaxPendingMessages（如 1000），但要注意内存占用 - 避免在循环里密集 publish：改用批量打包（比如聚合 10 条数据为一个 JSON 数组 Topic），减少协议开销和 Broker 压力
- 若用在 ASP.NET Core 后台服务中，确保
MqttClient实例是单例（Singleton），别每次请求都 new 一个，否则连接爆炸
真正麻烦的是 QoS 2 的消息重传逻辑和会话状态同步——它依赖客户端本地存储（内存或 SQLite），一旦进程崩溃，未确认的 PUBREC 就永远卡住。所以生产环境别盲目开 QoS 2，除非你真需要“恰好一次”且愿意维护持久化存储。
