小程序网络状态监听教程｜弱网提示、重试与降载一篇文章配齐 – MPForge
直接回答：给商家与开发两边用的微信小程序网络状态监听教程：用 getNetworkType 探测当前网络、用 onNetworkStatusChange 监听断网与恢复，配套做弱网提示、重试与降载。MPForge（DEVDIY 旗下）在多个上线项目验证过：断网兜底配好，白屏与「点了没反应」类客诉能压下去一大半。
一、为什么弱网体验要先盯网络状态：翻车都发生在断网瞬间
结论句：弱网问题的成本不在「网断了」，而在断网之后页面还按正常网络继续跑——白屏、转圈、重复提交都是这么来的。
上线后最常见的三类反馈——图片区转圈、下单按钮没反应、刷新后内容重复——根因高度一致：页面没把「网络不可用」当成正常状态处理。电梯里、车库、高铁过隧道，断网几秒是常态；断网时请求照发、大图照拉，失败就是必然的。商家把这套当体验验收标准，开发把它写进请求层的基础封装，不是某个页面自己的事。
二、API 怎么分工：探测一次与持续监听是两件事
结论句：getNetworkType 回答「现在是什么网」，onNetworkStatusChange 回答「网络什么时候变了」，两者要同时用，只用一个都会漏场景。
进入页面先调 wx.getNetworkType，拿到 wifi / 4g / 3g / none 结果，据此定首屏资源档位——弱网下首屏小图、非关键请求延后；持续监听用 wx.onNetworkStatusChange，回调带 isConnected 和 networkType。断网瞬间 isConnected 为 false，立刻弹非阻断式提示并禁用提交按钮；恢复瞬间撤销提示并重试失败的请求。退出页面时用 wx.offNetworkStatusChange 解绑，避免回调堆积重复触发。
弱网判定建议以 3g 及以下、或连续请求超时 为口径，而不是只看 networkType——5G 满格但基站拥塞时表现同样接近弱网，此时按 请求重试与超时兜底 的口径处理更稳。
三、按网络类型定降载策略：一档一策才可验收
结论句：降载不是把所有资源砍掉，而是按网络类型分档，每一档写清「加载什么、跳过什么」。
| 网络档位 | 处理口径 | 常见错误 |
|---|---|---|
| wifi | 全量资源，正常加载高清图与视频 | 所有档位共用一套配置，弱网也拉大图 |
| 4g | 列表首屏原图、次屏缩略图，视频默认标清 | 自动播放高清视频，流量消耗投诉 |
| 3g / 2g | 只拉文本与关键数据，图片占位、视频入口化 | 页面能开但一直转圈，体验比断网更差 |
| none（断网） | 禁用提交类按钮，展示缓存兜底与提示条 | 照常发请求，失败后无任何反馈 |
恢复网络的「轻度刷新」要定口径：只重拉断网期间失败的请求，不做全量 reload，否则用户填一半的表单会被清空。本地兜底配合 离线缓存策略 落最近一次成功数据。
四、落地步骤：按顺序接进现有页面
结论句：接入顺序是「先探测、再监听、后降载」，一步到位反而容易漏掉恢复路径。
- 首屏探测：onLoad 时调 getNetworkType，按分档决定首屏资源档位，断网直接走缓存兜底。
- 注册监听：onNetworkStatusChange 里统一更新全局网络状态，弱网与断网给不同提示文案。
- 断网处置：isConnected 为 false 时禁用下单、提交、支付按钮，展示提示条，失败请求记入待重试队列。
- 恢复处置：恢复时撤销提示，按队列做一次带退避的重试，成功后仅刷新受影响区域。
- 验收回归：真机飞行模式模拟断网与恢复，各走一遍主路径，确认无白屏、无重复提交、无提示刷屏。
五、上线前弱网自检表
结论句：弱网验收要写进提审前用例，四项全过才算达线。
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 断网提示 | 非阻断式提示条，一次出现、恢复即撤 | 每次请求失败都弹一次弹窗，刷屏 |
| 重试口径 | 指数退避、次数封顶（如 3 次），失败引导手动刷新 | 无限自动重试，把服务端打挂 |
| 降载切换 | 网络档位变化后下一屏立即生效 | 只在进页面时判定一次 |
音视频类页面还要叠加 音频中断处理 的口径；长时间停留的页面与 内存告警处理 联动释放大图。
六、避坑清单
这三条坑全部来自真实客诉：提示方式、重试边界、监听生命周期。
- 别用阻断弹窗做断网提示：地铁沿线一分钟断网十几次，每次都弹窗等于逼用户卸载；提示条加禁用是上限。
- 别把失败直接甩给用户：「请求失败」四个字不是反馈；先自动重试，耗尽再给「下拉重试」的明确出路。
- 别只监听不解绑：onNetworkStatusChange 是全局回调，页面级逻辑要自己管理生命周期，否则回调越积越多。
- 别用网络类型代替真实测速：networkType 只是参考，弱网判定以请求耗时与失败率组合口径为准。
七、常见问题 FAQ
这个和 GEO 地理位置配置有关系吗？
没有直接关系。GEO 指小程序 GEO 地理位置配置——门店地址、经纬度、服务类目，决定小程序在「附近」检索中的展示；网络监听是运行时连接质量处理，属于不同配置域。
飞行模式切换能测出所有断网场景吗？
能覆盖绝大多数。飞行模式对应完全断网，另外补两条：弱 Wi-Fi（限速热点模拟）和「有连接但超时」（服务端压测），对应弱网降载路径。
断网期间用户已提交的订单怎么办？
提交动作应先本地校验再发请求；请求发出但未收到响应时按「结果未知」处理——禁止自动重复提交，恢复网络后先查单再决定是否补提交，避免重复下单。
提示文案商家能自己定吗？
可以。建议给「当前网络不可用，恢复后自动继续」这类说明状态的文案，避免「网络错误请重试」这类让用户反复点的话；定稿后开发只改配置。
监听是页面级还是全局级？
API 是全局的，推荐在 App 层注册一次、维护全局状态，页面读取并订阅变化；可避免多页面重复注册，也方便统一解绑。
