sentry-miniapp 2.0:小程序与小游戏问题更好排查

“接口没报错，用户却没下成单。”“游戏一直在加载，但不知道卡在哪一步。”

小程序和小游戏上线后，开发者经常要从这样一句反馈开始排查。最缺的，是能够还原问题的线索。

10 月 11 日，我维护的开源项目 sentry-miniapp 发布了 2.0.0。它是社区维护的 Sentry SDK，支持微信等平台的小程序、微信与抖音小游戏，也适配 Taro、uni-app 小程序项目。

对我来说，维护一个监控 SDK，需要回答一个具体的问题：开发者拿到这些数据之后，接下来能查什么？

2.0 在已有的异常和性能监控基础上，补充业务指标、流式性能上报和运行可靠性修复。

一、业务没完成，也值得留下线索

以下单流程为例：请求正常返回，业务结果却是“库存不足”。代码没有抛出异常，用户也没能完成下单。

1.x 可以通过消息和上下文记录某次业务失败。2.0 新增 Metrics，可以进一步记录业务计数和数值分布。例如，在“库存不足”分支增加一次计数，每次下单结束记录一次耗时，观察这类结果出现了多少次、耗时如何分布。

在小游戏里，也可以主动记录关卡开始与完成的次数、单局时长。

我希望开发者能分清两件事：代码运行是否正常，业务流程是否完成。围绕关键结果和耗时主动记录指标，能为后一个问题补充依据。

哪些结果值得记录，仍由业务决定。先围绕最关心的一个流程留下几项数据，再结合错误和上下文观察，就能开始使用。

二、排查长流程，先拿到已完成步骤的数据

小程序上传图片，要经过压缩、上传和服务端处理；小游戏进入一局，也可能要等待资源加载、登录和房间连接。用户看到的是“还没结束”，开发者需要知道时间花在了哪一步。

1.x 已经能用 span，也就是一次操作的性能记录，测量请求和业务步骤的耗时。2.0 改进了长流程的数据上报方式：已完成的子操作可以按批次发送，减少等待整个流程收尾的时间。

小游戏的帧率与卡顿统计在 1.x 已有。2.0 将这类持续采集改为默认关闭，需要时再启用。

三、监控代码也要可靠

维护监控 SDK，我同样在意它自己的运行行为。

2.0 升级到 @sentry/core 11.x。在开发和审查过程中，我重点检查了异常来源、重复初始化后的资源回收，以及关闭或撤回采集时的发送行为，并修复了其中发现的问题。

正确保留异常来源，释放旧实例的资源，处理好关闭和撤回期间的发送，都是让监控值得信任的基础。

四、是否要升级到 2.x 版本

作为维护者，我的建议是先问自己：现在缺少什么线索，2.0 能不能补上？升级需要配置调整和验证，这些投入应该对应实际需求。

如果 1.x 已经稳定运行，也能满足异常排查需求，可以继续使用已验收的版本。需要业务 Metrics 或新的流式性能数据，再安排迁移。

后台条件也要一起确认：官方 Sentry 云服务可接收 2.0 数据，现有项目和 DSN 可以沿用；自建 Sentry 的官方支持基线是 26.4.2 及以上。较旧后台建议继续使用已验收的 1.x。

2.0 的性能数据使用 span/v2，没有旧 transaction 格式的兼容开关。集成 API 和默认行为也有变化，升级前请按迁移指南检查集成、dataCollection、采样与生命周期配置。

五、最后

我希望使用 sentry-miniapp 的小程序和小游戏开发者，在收到一条模糊反馈后，能找到可追查的线索，做出有依据的判断。这也是我在 2.0 中最看重的价值。

你的小程序或小游戏，目前最难定位的是哪类线上问题？欢迎在评论里聊聊。具体接入问题，也可以附上复现步骤到 GitHub 反馈，方便一起追查。

项目与正式版说明：https://github.com/lizhiyao/sentry-miniapp/releases/tag/v2.0.0

小程序快速接入：https://sentry-miniapp.pages.dev/guide/getting-started

小游戏接入：https://sentry-miniapp.pages.dev/guide/minigame

1.x 升级指南：https://sentry-miniapp.pages.dev/guide/migration-2.0

问题反馈：https://github.com/lizhiyao/sentry-miniapp/issues/new/choose