sentry-miniapp 1.11.0 → 1.11.2

package/README.en.md

@@ -7,9 +7,12 @@
 ![test coverage](https://img.shields.io/badge/test%20coverage-100%25-brightgreen.svg)
 [![Sentry Community SDK](https://img.shields.io/badge/Sentry-Community%20SDK-362d59?logo=sentry)](https://docs.sentry.io/platforms/#sdks-supported-by-our-community)
 [![license](https://img.shields.io/github/license/lizhiyao/sentry-miniapp)](./LICENSE)
+[![docs](https://img.shields.io/badge/docs-sentry--miniapp.pages.dev-3eaf7c?logo=readthedocs&logoColor=white)](https://sentry-miniapp.pages.dev/)
 
 [简体中文](./README.md) | English
 
+> **📖 Documentation**: [https://sentry-miniapp.pages.dev/](https://sentry-miniapp.pages.dev/) — getting started, capability matrix, FAQ, Source Map setup, and examples, with nav and search. (Chinese for now)
+
 A **mini program monitoring SDK** built on `@sentry/core`, providing **error monitoring**, **performance monitoring**, offline caching, and distributed tracing. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs, **WeChat / Douyin mini games**, and cross-platform frameworks (Taro / uni-app).
 
 > **What are Mini Programs?** Mini programs (小程序) are lightweight apps that run inside super-apps like WeChat, Alipay, and ByteDance/Douyin. They form a massive ecosystem in China with **hundreds of millions of daily active users**, but have no direct equivalent in the Western tech stack. Think of them as a hybrid between PWAs and native apps, but hosted within a platform's sandbox.
@@ -403,6 +406,84 @@ export default Sentry;
 
 Both sides report to the same Sentry DSN so all errors land in a single project. For Taro, use `process.env.TARO_ENV === 'h5'` to branch similarly.
 
+### 4. Are network requests included with error events?
+
+**Yes, and it's on by default.** The SDK enables `NetworkBreadcrumbs` out of the box, which patches `wx.request` / `my.httpRequest` and records each request as a `category: xhr` breadcrumb. Those breadcrumbs ride along with the **next captured error event** (same as `@sentry/browser`), so you'll see the request trail leading up to the error in the event's **Breadcrumbs** section.
+
+- **Fields by default:** `url` / `method` / `status_code` / `duration`; failed requests are `error` level, slow ones (>3s) are `warning`.
+- **Bodies are NOT included by default.** Enable `traceNetworkBody: true` to capture request/response bodies (with built-in sensitive-field scrubbing; use `denyBodyUrls` to exclude specific URLs):
+
+  ```js
+  Sentry.init({ dsn: '...', traceNetworkBody: true });
+  ```
+
+- **No extra config for uni-app / Taro:** `uni.request` / `Taro.request` ultimately call the patched global `wx.request`, so they're captured too.
+
+If an error has no network breadcrumb, it's usually one of:
+
+1. **No request happened before the error fired** (e.g. calling `captureException` right on page load). To verify, make a request first and trigger the error in its callback:
+
+   ```js
+   wx.request({
+     url: 'https://httpbin.org/get',
+     success() {
+       Sentry.captureException(new Error('net test'));
+     },
+   });
+   ```
+
+   You should then see a `category: xhr` breadcrumb on the event.
+
+2. **`Sentry.init` ran after the request.** The patch is installed during `init`, so requests fired before `init` aren't captured. Always call `Sentry.init` before `App()` / any business request.
+
+### 5. Errors in uni-app (Vue) components aren't reported / reporting rate is very low?
+
+With **uni-app** (Vue under the hood) you may hit "`sampleRate` is 1 but only an occasional error shows up". The reason: **Vue catches errors thrown inside components (render / lifecycle / watchers / methods invoked from `@click`) with its own error handler — by default it only logs to console and does NOT bubble them to `wx.onError`**, so the SDK never sees them. Only errors that escape Vue (e.g. `setTimeout` callbacks, unhandled promises, hard crashes) get through, which is why reporting looks sporadic.
+
+Wire Vue's `errorHandler` to Sentry so component errors are reported:
+
+**uni-app Vue3 (`main.js` / `main.ts`, the current default):**
+
+```js
+import Sentry from '@/utils/sentry'; // your sentry-miniapp init wrapper
+import { createSSRApp } from 'vue';
+import App from './App.vue';
+
+export function createApp() {
+  const app = createSSRApp(App);
+  app.config.errorHandler = (err, instance, info) => {
+    Sentry.captureException(err, { extra: { lifecycleHook: info } });
+    console.error(err);
+  };
+  return { app };
+}
+```
+
+**Vue2 (older uni-app):**
+
+```js
+Vue.config.errorHandler = (err, vm, info) => {
+  Sentry.captureException(err);
+  console.error(err);
+};
+```
+
+> **Taro is not Vue.** Taro defaults to **React** (and also supports Vue). With **Vue**, wire `errorHandler` the same way; with **React**, React does not silently swallow component errors like Vue (an uncaught render error propagates upward), but you can add an **Error Boundary** to forward render errors to Sentry with richer context:
+>
+> ```jsx
+> class SentryBoundary extends React.Component {
+>   componentDidCatch(error, info) {
+>     Sentry.captureException(error, { extra: info });
+>   }
+>   render() {
+>     return this.props.children;
+>   }
+> }
+> // Wrap your root: <SentryBoundary><App /></SentryBoundary>
+> ```
+
+This also improves delivery: once `errorHandler` / the boundary catches the error the app keeps running, so the in-flight report request completes (a hard crash would otherwise kill it).
+
 ---
 
 ## Documentation

package/README.md

@@ -7,9 +7,12 @@
 ![test coverage](https://img.shields.io/badge/test%20coverage-100%25-brightgreen.svg)
 [![Sentry Community SDK](https://img.shields.io/badge/Sentry-Community%20SDK-362d59?logo=sentry)](https://docs.sentry.io/platforms/#sdks-supported-by-our-community)
 [![license](https://img.shields.io/github/license/lizhiyao/sentry-miniapp)](./LICENSE)
+[![文档站 docs](https://img.shields.io/badge/docs-sentry--miniapp.pages.dev-3eaf7c?logo=readthedocs&logoColor=white)](https://sentry-miniapp.pages.dev/)
 
 简体中文 | [English](./README.en.md)
 
+> **📖 文档站**：[https://sentry-miniapp.pages.dev/](https://sentry-miniapp.pages.dev/) —— 快速接入、能力矩阵、FAQ、Source Map 配置、示例索引，带导航与搜索。
+
 一个基于 `@sentry/core` 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序，以及微信 / 抖音等**小游戏**，并兼容 Taro / uni-app 等跨端框架。
 
 > **📰 最新文章**：[《我给 Sentry 提了个 PR，后来 sentry-miniapp 进了官方文档》](https://juejin.cn/post/7636106283963760681) — sentry-miniapp 已被收录进 Sentry 官方文档的 community-supported SDK 列表，这篇文章记录这件事的来龙去脉。觉得有用请帮忙点个 ⭐ Star，让更多小程序团队找到它。
@@ -418,6 +421,84 @@ export default Sentry;
 
 两端上报同一个 Sentry DSN，可以在同一个 Project 里聚合查看错误。Taro 用户可以用类似的 `process.env.TARO_ENV === 'h5'` 判断分端引入。
 
+### 4. 网络请求会随错误事件一起上报吗？
+
+**会，且默认开启。** SDK 默认启用 `NetworkBreadcrumbs`，自动劫持 `wx.request` / `my.httpRequest`，把每个网络请求记成 `category: xhr` 的面包屑，随**下一个被捕获的错误事件**一起上报（与 `@sentry/browser` 默认行为一致）。在 Sentry 错误详情的 **Breadcrumbs** 区即可看到出错前的请求链路。
+
+- **默认带的字段**：`url` / `method` / `status_code` / `duration`；失败请求标 `error` 级、慢请求（>3s）标 `warning` 级。
+- **默认不带请求 / 响应体**。需要 body 时开启 `traceNetworkBody: true`（内置常见敏感字段脱敏，可用 `denyBodyUrls` 排除指定 URL）：
+
+  ```js
+  Sentry.init({ dsn: '...', traceNetworkBody: true });
+  ```
+
+- **uni-app / Taro 无需额外配置**：`uni.request` / `Taro.request` 最终都会走到被包裹的全局 `wx.request`，照常记录。
+
+如果错误里没有网络面包屑，多半是这两点之一：
+
+1. **错误触发前没发过请求**（比如一进页面就手动 `captureException`，自然没有请求面包屑）。验证方式：先发一个请求，在回调里再触发错误——
+
+   ```js
+   wx.request({
+     url: 'https://httpbin.org/get',
+     success() {
+       Sentry.captureException(new Error('net test'));
+     },
+   });
+   ```
+
+   到事件 Breadcrumbs 里应能看到 `category: xhr` 那条。
+
+2. **`Sentry.init` 晚于请求执行**：面包屑包裹在 `init` 时装上，`init` 之前发出的请求抓不到。务必让 `Sentry.init` 在 `App()` / 任何业务请求**之前**执行。
+
+### 5. uni-app（Vue）组件内的错误没上报 / 上报率很低？
+
+如果你用 **uni-app**（底层是 Vue），可能遇到「`sampleRate` 设成 1，却只偶尔上报一条」的情况。原因：**Vue 会用自己的错误处理接住组件内（render / 生命周期 / watch / 模板 `@click` 调用的方法）抛出的错误，默认只打印 console，不会再冒泡到 `wx.onError`**，于是 SDK 捕获不到。能上来的只剩「逃逸出 Vue」的那部分（`setTimeout` 回调、未处理 promise、硬崩溃），所以看起来只偶尔上报。
+
+把 Vue 的 `errorHandler` 接到 Sentry，组件内错误就会上报：
+
+**uni-app Vue3（`main.js` / `main.ts`，现在默认）：**
+
+```js
+import Sentry from '@/utils/sentry'; // 你封装的 sentry-miniapp 初始化
+import { createSSRApp } from 'vue';
+import App from './App.vue';
+
+export function createApp() {
+  const app = createSSRApp(App);
+  app.config.errorHandler = (err, instance, info) => {
+    Sentry.captureException(err, { extra: { lifecycleHook: info } });
+    console.error(err);
+  };
+  return { app };
+}
+```
+
+**Vue2（uni-app 旧版）：**
+
+```js
+Vue.config.errorHandler = (err, vm, info) => {
+  Sentry.captureException(err);
+  console.error(err);
+};
+```
+
+> **Taro 不是 Vue。** Taro 默认用 **React**（也支持 Vue）。用 **Vue** 时同理接 `errorHandler`；用 **React** 时，React 不会像 Vue 那样静默吞掉组件错误（未捕获的渲染错误会向上抛），但你可以加一个**错误边界（Error Boundary）**把渲染错误更完整地转给 Sentry：
+>
+> ```jsx
+> class SentryBoundary extends React.Component {
+>   componentDidCatch(error, info) {
+>     Sentry.captureException(error, { extra: info });
+>   }
+>   render() {
+>     return this.props.children;
+>   }
+> }
+> // 用它包住根组件：<SentryBoundary><App /></SentryBoundary>
+> ```
+
+接上之后还顺带提升送达率——`errorHandler` / 错误边界接住后应用不崩，上报请求能正常发完（硬崩溃会把还在飞的上报请求一起带走）。
+
 ---
 
 ## 📖 文档导航