lizhiyao / sentry-miniapp

Sentry Miniapp SDK 一个基于 (v10.45.0) 核心构建的**多端小程序异常与性能监控 SDK**。旨在为小程序开发者提供与 Web 端一致的、强大且现代的 Sentry 监控体验。 > **💡 版本说明** > > - ：全新架构，基于 Sentry V10 核心，全面支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序及主流跨端框架（Taro / uni-app 等）。 > - ：旧版本，已停止维护。 --- ✨ 核心特性 • **🚀 现代架构**：基于最新的 Sentry JavaScript V10 SDK 核心模块构建。 • **📱 真正的多端支持**：内置 API 抹平引擎，一套代码无缝兼容**微信、支付宝、字节、百度、QQ、钉钉、快手**等主流小程序平台。 • **🎯 全自动异常捕获**：无需侵入业务代码，自动监听并上报生命周期异常（ 、 、 、 ）。 • **🍞 丰富的上下文面包屑**：自动记录设备信息、用户点击/触摸操作、网络请求（XHR/Fetch）、以及页面路由导航路径。 • **🗺️ 内置 SourceMap 路径抹平**：自动处理微信、支付宝、字节等多端小程序的虚拟堆栈路径，配合 sentry-cli 极简实现 SourceMap 解析。 • **📡 弱网离线缓存机制**：专为小程序网络环境设计，断网或发送失败时自动缓存 Event 到本地 Storage，网络恢复后静默重试上报，确保数据不丢失。 • **⚡ 深度性能监控**：集成小程序 Performance API，全面采集导航性能（FCP/LCP）、渲染性能、资源加载耗时及用户自定义性能标记。 • **�️ 智能降噪与过滤**：内置强大的错误去重和采样率控制机制，避免日志风暴。 • **🔧 跨端框架友好**：完美支持在 Taro、uni-app 等第三方多端编译框架中集成使用。 --- 📦 安装 推荐使用 进行安装。 > **注意：** 及以上版本已优化构建策略（内联依赖），**无需**再额外安装 。 *提示：如果您不使用 npm，也可以直接将项目仓库中 文件复制到小程序项目中引入。* --- 🚀 快速接入 • 前置准备 • 确保您有可用的 Sentry 平台账号（可以使用 官方 Sentry SaaS 或 私有化部署服务）。 • **非常重要**：在各平台的小程序管理后台，将 Sentry 的上报接口域名添加到 合法域名列表中。 • 初始化 SDK 请在小程序入口文件（如 或 ）的**最顶部**（调用 之前）初始化 Sentry。 --- 📚 常用进阶用法 初始化完成后，SDK 会自动在后台工作。您也可以使用以下 API 进行手动埋点或主动上报。 手动异常与消息上报 丰富上下文信息 (Context & Breadcrumbs) 自定义性能测速 (Performance) --- 🗺️ Source Map 支持与配置 在小程序中，报错堆栈的路径通常是各种虚拟路径（如 ），这导致直接上传的 Source Map 无法被 Sentry 正确解析。 SDK 内部已经为您解决了这个痛点： 只要在 时开启了 （默认开启），SDK 会在报错时自动拦截并抹平各平台的虚拟路径，统一替换为标准前缀 。 您**只需要在打包上传 Source Map 时，确保配置的 为 即可**。 **使用 sentry-cli 上传示例：** *(注：在微信开发者工具上传代码时，请**务必关闭**工具自带的“ES6转ES5”和“代码压缩”功能，将这些工作交给 Webpack/Vite 等构建工具，以防行列号错位。)* --- ❓ 常见问题 (FAQ) • 初始化后无法自动上报异常，必须在 中手动调 API 吗？ **完全不需要**。 在初始化时会自动劫持并注册平台底层的全局错误监听（如 ）。只要确保 在 调用**之前**执行，它就能自动捕获所有未处理的 JS 异常。 如果发现没上报，请检查： • Sentry 域名是否加入了小程序后台合法域名。 • (采样率) 是否被意外设置得太低。 • 微信开发者工具某些环境下的报错不会触发底层 ，建议在**真机预览**下测试。 • 这个 SDK 支持 Session Replay (屏幕操作回放) 吗？ 目前 **不支持** 。 Sentry 官方的 Replay 功能强依赖于浏览器标准 DOM 环境（通过 rrweb 录制）。小程序采用双线程架构且没有开放标准 DOM 接口，无法直接复用。建议通过完善**Breadcrumbs（面包屑路径）**结合**自定义日志**来还原用户操作现场。 --- 🤝 参与贡献 我们非常欢迎开发者提交 或通过 提出宝贵意见！ 要参与本地开发： • 安装依赖 • 启动监听编译 • 运行完整的单元测试与集成测试套件 --- 💬 联系与交流 遇到问题？想探讨小程序监控方案？欢迎加入我们的交流群。 由于微信群二维码有 7 天时效性限制，请添加作者微信（**备注 sentry-miniapp**），由作者邀请您入群：