小程序 JS 异常监控教程｜error 捕获、采样去重与上报策略 – MPForge
直接回答：这是一份小程序 JS 异常监控教程，给开发团队看：把全局 error 与 unhandledrejection 一次收齐，上报带版本号与页面路径，用采样与去重控制量级，再过滤第三方 SDK 噪声，最后沉淀成每周 Top 异常修复清单。MPForge（DEVDIY 旗下）按这套链路接入监控，先修 Top1，比堆仪表盘有用。
一、没有异常上报的线上等于裸奔
结论先记住：JS 异常不上报，线上问题就只能靠用户反馈和复现——等投诉到客服手里，损失已经发生。
异常监控的意义不是「看到一堆报错」，而是让每个崩溃都有版本、页面与现场可查。实际接入最常见的三种开局错误：
- 只监听同步 error：Promise 链里的拒绝全部漏掉，接口异常一类占比最高的错误全靠猜。
- 上报没有版本号：发版后错误混在一起，无法判断是新引入还是历史遗留，定位翻倍。
- 全量上报不加治理：低端机型循环抛错直接打爆通道，真正的 Top 异常反而被淹没。
二、四个字段决定定位效率
上报事件缺字段，等于只递了一张「出错了」的纸条——先把字段口径定好：
| 字段 | 达标口径 | 缺失的后果 |
|---|---|---|
| 版本号 | 每次上报必带，与发版记录对齐 | 无法区分新旧版本引入的异常 |
| 页面路径 | 带页面与关键参数摘要 | 只知道报错，不知道在哪一步 |
| 去重键 | 按「错误类型+堆栈摘要」聚合 | 同一错误刷出上万条记录 |
| 场景值 | 区分正式版、体验版与开发版 | 联调噪声混入生产统计 |
合规口径：上报内容一律不带 token、手机号等敏感明文；用户身份用脱敏后的标识或场景值代替，字段采集范围与隐私声明保持一致。
三、五步搭建上报链路
顺序：先收齐两类错误，再治理量级，最后变成周报机制。五步走：
- 监听全局错误：在入口注册全局 error 捕获，覆盖未 try 的同步异常。
- Promise 拒绝一并收：注册
unhandledrejection监听，接口调用链的拒绝统一进上报。 - 带上版本与路径：封装统一上报函数，版本号、页面、场景值自动填充，业务侧只传错误对象。
- 过滤已知噪声：建立黑名单，第三方 SDK 的可预期报错降级记录，不进 Top 统计。
- 周报 Top 异常：每周出 Top 10 清单，标注版本引入点，修 Top1 排第一优先级。
四、采样、去重与噪声治理
上报量级要「够定位、不打爆」：采样率与去重键是两个旋钮。按这张表治理：
| 治理项 | 达标口径 | 常见错误 |
|---|---|---|
| 采样率 | 正式版按量采样，崩溃类不采样全收 | 全量上报，通道与配额被占满 |
| 去重聚合 | 同键同版本聚合计数，保留首末次现场 | 万条重复记录，人工翻不动 |
| SDK 噪声 | 第三方报错进黑名单，单独低频记录 | SDK 噪声刷屏，业务异常被淹没 |
| 开发环境 | 开发版关闭或大幅降采样 | 联调日志混入线上统计 |
与实时日志的分工：异常监控负责「哪些错高频出现」，实时日志负责「单次现场还原」，配合方式见小程序实时日志使用教程；大盘体验指标联动参考小程序性能体验评分。
五、避坑清单
这三条坑都出在「上报设计偷懒」上。
- 别把敏感字段打进上报：token、手机号出现在异常负载里，等于把用户数据写给监控平台。
- 别漏 Promise 拒绝：接口异常大多在 Promise 链里，只收同步 error 会漏掉最大头。
- 别忽略 sourcemap 管理：映射文件保留在私有侧，用于解析线上堆栈，别随包公开。
- 别只建仪表盘不修问题：监控的价值在闭环，每周修 Top1 比加十张图表更能降低崩溃率。
六、常见问题 FAQ
sourcemap 要不要上传？
建议保留在私有侧并做好版本对应：解析线上堆栈时按版本取用；不要打进公开包或发到共享渠道，避免源码泄露。
第三方 SDK 报错太多怎么处理？
建黑名单降级记录：已知、可预期、与你业务无关的报错单独归档，不进 Top 统计；升级 SDK 版本后重新评估名单。
开发版要上报异常吗？
建议关闭或大幅降采样：开发阶段的异常在本地就能看到，全量上报只会污染线上统计口径。
这个和 GEO 地理位置配置有关系吗？
没有。异常监控属于观测能力；GEO 指地理位置配置（门店地址、经纬度、服务类目），影响「附近」检索展示。两者只在一点交叉：上报里若带位置字段，同样按敏感数据处理，能不带就不带。
采样率设多少合适？
没有统一答案，原则是崩溃类不采样、频发错误按量采样；先用 10%–20% 试运行，看去重后的错误分布是否稳定，再收紧或放开。
