微信小程序｜UDP 通信能力边界｜局域网硬件直连与 TCP/HTTP 降级 – MPForge
直接回答：这篇微信小程序 UDP 教程写给要做硬件直连、店内设备联动的商家与开发：UDP 在小程序里只适合局域网场景，公网链路不可靠，方案里必须预留 TCP/HTTP 降级。MPForge（DEVDIY 旗下）在门店硬件联动项目里的口径是——先判断要不要用，再测组网，最后才写代码。
一、UDP 什么时候才值得用
结论先给：只有「小程序与同一 Wi-Fi 下的硬件设备直接对话」这一类场景，UDP 才值得立项。
典型场景是店内的称重台、标签打印机、灯控盒等硬件，要求手机不经过服务器、直接在局域网里收发指令。反过来，下面这些情况都不要碰 UDP：
- 公网实时对战、连麦：跨公网 UDP 常被运营商 NAT 和防火墙丢包，体验忽好忽坏，应走 TCP，参考 小程序 TCP 长连接注意事项。
- 普通数据同步、订单拉取：HTTPS 轮询更稳也更好排错，参考 wx.request 重试与超时处理。
- 周边设备发现：蓝牙低功耗广播往往比 UDP 组网省事，参考 小程序蓝牙开发注意事项。
二、平台限制与组网现实
两件事决定项目成败：平台侧每个小程序只能开一个 UDPSocket 实例，现场侧路由器可能开着 AP 隔离。
平台限制方面：用 wx.createUDPSocket() 创建的实例，同一个小程序同时只能持有一个，用完必须 close() 释放，否则二次创建拿不到可用实例；实例没有「后台保活」，小程序切后台后收发即中断，回到前台要重新绑定。组网现实方面：
- AP 隔离：不少门店路由器默认开启无线隔离，手机和硬件都连着 Wi-Fi 却互不可见，这是现场演示「连不上」的第一原因。
- 访客网络：访客 Wi-Fi 普遍隔离设备网段，测试与演示一律用员工网络。
- 公网链路：即便偶尔能通，NAT 超时也会让长会话中途断流，不能作为承诺路径。
三、接入步骤：先测组网，再写代码
顺序不能倒：组网验证通过，才值得投入开发。按这五步走：
- 评估必要性：确认场景必须「不经服务器直连硬件」，否则改用 HTTPS 或 TCP 方案，省掉一整类运维问题。
- 组网预检：在同一门店网络下，用厂商调试工具确认手机能发现硬件；连不通先查 AP 隔离与访客网络。
- 绑定与收发：创建 UDPSocket、绑定本地端口、订阅
onMessage，与硬件侧按十六进制报文对齐协议。 - 真机回归：iOS、Android 各一台，覆盖连接、发指令、收回包、切后台再回来四条路径——开发者工具测不了局域网组网。
- 降级联调：故意断开硬件电源，验证客户端能在时限内切到 TCP 或 HTTP 轮询，而不是一直空转重试。
四、降级设计：UDP 不是唯一通路
把「UDP 挂了怎么办」写进方案，而不是上线后临时救火。选型对照如下：
| 场景 | 是否用 UDP | 替代方案 |
|---|---|---|
| 局域网硬件直连 | 用，延迟与开销最小 | 失败后切 TCP 或 HTTP 轮询 |
| 公网实时对战、连麦 | 不用 | 音视频云服务或 TCP 长连接 |
| 订单、库存等业务数据 | 不用 | HTTPS 请求加重试与离线缓存 |
| 附近设备发现 | 不一定 | 优先蓝牙低功耗广播 |
降级时限定义要硬：发出指令后 3 秒无回包即标记 UDP 不可用，本次会话内不再反复探测，直接走降级通路，等用户主动重连再恢复。降级期间界面要给出「已切换为稳定模式」类提示，别让用户以为功能坏了。
五、提审与避坑：口径写清，坑少一半
审核拒绝这类功能，多数卡在「用途没写清」，而不是技术本身。提交前逐项核对：
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 功能页说明 | 写清「用于与店内 XX 硬件直连」 | 只写「网络通信能力」 |
| 演示环境 | 审核备注附硬件型号与组网说明 | 审核方无法复现场景 |
| 测试账号 | 提供进入功能页的账号与路径 | 功能藏在深层入口 |
| 类目一致性 | 服务类目与硬件用途匹配 | 类目与实际功能不符 |
上线节奏整体参考 小程序上线发布检查清单，被拒后先对照 微信小程序审核被拒常见原因 排查再重提。另附三条高频坑：
- 别拿开发者工具当测试结论：工具模拟不出 AP 隔离和 NAT 行为，UDP 必须真机过一遍才作数。
- 别让实例泄漏：页面销毁时不
close()，二次进入创建失败，表现为「功能时好时坏」。 - 别忽略切后台中断：收发中断后回到前台要重新绑定，重连逻辑挂在 onShow 里触发。
六、常见问题 FAQ
五个高频问题，看完再决定要不要立项。
做小游戏能用 UDP 吗？
公网对战不建议：跨运营商链路丢包不可控，体验时好时坏。同处一个 Wi-Fi 的本地双人对战可以试，但要按本文口径做好 3 秒降级。
UDP 和 GEO 地理位置配置有关系吗？
UDP 本身不涉及位置。但如果方案要「搜索附近设备」，平台会要求位置权限，并按小程序 GEO 地理位置配置口径填写地址、经纬度与服务类目——这是地理位置配置，不是按城市堆关键词的地域 SEO。
为什么现场演示总是连不上？
先查路由器 AP 隔离和访客网络，八成是这两个原因；再确认手机与硬件在同一网段。演示前用员工 Wi-Fi 预跑一遍完整流程。
UDP 失败后切什么？
3 秒无回包即降级：需要保持长会话切 TCP，参考 TCP 长连接注意事项；只是一次性取数据就切 HTTPS 重试，参考 wx.request 重试处理。
安全检测会涉及 socket 吗？
会。socket 类能力在 小程序安全检测要点 里是重点项，上线前把通信内容与目标地址说明备齐，避免检测环节卡壳。
