sentry-miniapp 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# 更新日志
+
+本文档记录了 sentry-miniapp 项目的所有重要变更。
+
+## [1.4.0] - 2026-03-23
+
+### 新增
+
+- ✨ 新增 `NetworkBreadcrumbs` 集成：支持抓取网络请求的 Request Body 和 Response Body。通过 `traceNetworkBody: true` 开启，方便深度排查接口异常。
+- ✨ 离线缓存上限可配置：在 `Sentry.init` 中新增 `offlineCacheLimit` 选项，允许开发者根据业务场景调大离线重试队列（默认 30）。
+- 🚀 支持全平台自动构建同步：重构构建脚本，`npm run build` 现在会自动将产物同步至示例工程，提升本地开发和直接拷贝单文件用户的体验。
+
+### 修复 & 优化
+
+- 🐛 修复无限死循环：在 `NetworkBreadcrumbs` 中自动忽略了配置的自托管（Self-Hosted）Sentry DSN 域名以及 `sentry.io`，防止上报请求被拦截。
+- 🗑️ 废弃 `showReportDialog`：小程序环境不支持 Sentry 官方 HTML 弹窗，已废弃该方法并输出清晰的警告，文档中增加了自定义 UI + `captureFeedback` 的最佳实践。
+- 📦 优化主包体积说明：在 README 中增加了关于“利用分包异步化实现 0KB 主包占用”的详细指南。
+- 🔍 优化 NPM 发现率：补充了全量的小程序平台和跨端框架中英文关键词。
+- 📚 文档精简：合并并删除了冗余的 `DEVELOPMENT_GUIDE.md`。
+
+## [1.3.1] - 2026-03-23
+
+### 修复
+
+- 🐛 修复事件上报中出现大量 `undefined` 值的问题
+- 🔧 改进系统信息收集逻辑，为所有可能为 undefined 的字段提供默认值
+- ✅ 增强 `getSystemInfo` 函数的健壮性，确保返回的数据结构完整
+- 🎯 改进事件构建器中的系统信息处理，提供完整的回退机制
+
+### 新增
+
+- 🧪 新增系统信息处理的测试用例，验证 undefined 字段的处理
+- 🧪 新增系统信息不可用时的回退值测试
+
+## [1.0.1-beta.1] - 2025-01-07
+
+### 修复
+
+- 🐛 修复 Performance API 集成中的 TypeError 错误 (`entries.forEach is not a function`)
+- 🔧 为不同的 PerformanceObserver 回调参数格式添加健壮处理
+- ✅ 改进与微信小程序 PerformanceObserver 实现的兼容性
+
+### 改进
+
+- 🎯 增强 `_handlePerformanceEntries` 方法以处理各种条目格式：
+  - 标准数组格式
+  - 单个对象格式
+  - PerformanceObserverEntryList 类对象
+  - 无效/null 参数（优雅处理）
+
+### 新增
+
+- 🧪 为不同 Performance API 条目格式添加额外测试用例
+
+## [未发布]
+
+### 新增
+
+- ✅ 大幅提升测试覆盖率，新增 274+ 测试用例
+- 🧪 新增 `crossPlatform.test.ts` - 测试平台检测、SDK获取和系统信息功能
+- 🧪 新增 `eventbuilder.test.ts` - 测试事件构建、异常处理和消息格式化
+- 🧪 新增 `polyfills.test.ts` - 测试 polyfill 功能
+- 🧪 新增 `version.test.ts` - 测试版本信息导出
+- 🧪 新增 `dedupe.test.ts` - 测试去重集成功能
+- 🧪 新增 `router.test.ts` - 测试路由集成功能
+- 📁 新增 `integration-tests/` 目录 - 包含端到端集成测试
+- 🔧 新增开发模式监听构建 (`npm run dev`)
+- 📚 完善开发文档和贡献指南
+
+### 改进
+
+- 🧪 增强 `helpers.test.ts` - 补充更多工具函数测试
+- 🔧 修复测试隔离问题 - 解决模块缓存导致的测试干扰
+- 🎯 优化测试结构 - 改进异步导入和测试期望值
+- 📝 更新 README.md - 反映最新功能和测试状态
+- 📝 更新 DEVELOPMENT.md - 添加测试和质量保证指南
+- 🏗️ 改进构建配置 - 支持开发和生产模式
+
+### 移除
+
+- 🗑️ 清理过时文件 - 移除 `test-scripts` 目录下的调试脚本
+- 🧹 重构测试脚本 - 将调试脚本移至 `integration-tests` 目录
+
+### 修复
+
+- 🐛 修复 `crossPlatform.test.ts` 中的测试失败问题
+- 🐛 解决模块缓存导致的测试隔离问题
+- 🔧 修复 TypeScript 类型错误
+- ✅ 确保所有测试稳定通过
+
+---
+
+## 版本说明
+
+### 语义化版本控制
+
+本项目遵循 [语义化版本控制](https://semver.org/lang/zh-CN/) 规范：
+
+- **主版本号**：不兼容的 API 修改
+- **次版本号**：向下兼容的功能性新增
+- **修订号**：向下兼容的问题修正
+
+### 变更类型
+
+- **新增** - 新功能
+- **改进** - 对现有功能的改进
+- **修复** - 问题修复
+- **移除** - 移除的功能
+- **安全** - 安全相关的修复
+- **废弃** - 即将移除的功能
+
+### 图标说明
+
+- ✅ 完成的功能
+- 🧪 测试相关
+- 🔧 开发工具
+- 📚 文档
+- 🐛 Bug 修复
+- 🎯 性能优化
+- 🏗️ 构建系统
+- 📁 文件结构
+- 🗑️ 删除
+- 🧹 重构

package/README.md

@@ -22,6 +22,7 @@
 - **📱 真正的多端支持**：内置 API 抹平引擎，一套代码无缝兼容**微信、支付宝、字节、百度、QQ、钉钉、快手**等主流小程序平台。
 - **🎯 全自动异常捕获**：无需侵入业务代码，自动监听并上报生命周期异常（`onError`、`onUnhandledRejection`、`onPageNotFound`、`onMemoryWarning`）。
 - **🍞 丰富的上下文面包屑**：自动记录设备信息、用户点击/触摸操作、网络请求（XHR/Fetch）、以及页面路由导航路径。
+- **🗺️ 内置 SourceMap 路径抹平**：自动处理微信、支付宝、字节等多端小程序的虚拟堆栈路径，配合 sentry-cli 极简实现 SourceMap 解析。
 - **📡 弱网离线缓存机制**：专为小程序网络环境设计，断网或发送失败时自动缓存 Event 到本地 Storage，网络恢复后静默重试上报，确保数据不丢失。
 - **⚡ 深度性能监控**：集成小程序 Performance API，全面采集导航性能（FCP/LCP）、渲染性能、资源加载耗时及用户自定义性能标记。
 - **�️ 智能降噪与过滤**：内置强大的错误去重和采样率控制机制，避免日志风暴。
@@ -67,9 +68,14 @@ Sentry.init({
   enableSystemInfo: true, // 自动采集系统与设备信息
   enableUserInteractionBreadcrumbs: true, // 自动记录用户点击行为
   enableNavigationBreadcrumbs: true, // 自动记录页面路由跳转
+  traceNetworkBody: true, // [新增] 是否在面包屑中记录网络请求的请求体和响应体 (默认 false)
   
   // --- 离线缓存与可靠性 ---
   enableOfflineCache: true, // 开启断网离线缓存与重试机制 (默认开启)
+  offlineCacheLimit: 30, // 离线缓存的最大事件数 (默认 30，可调大以防弱网下丢失更多数据)
+  
+  // --- SourceMap 支持 ---
+  enableSourceMap: true, // 开启自动将堆栈的虚拟路径转为统一格式，配合上传 sourcemap 时的 --url-prefix "app:///"
   
   // --- 性能与采样率 ---
   sampleRate: 1.0, // 异常上报采样率 (0.0 - 1.0)
@@ -147,6 +153,113 @@ Sentry.measurePerformance('fetch-user-data', 'api-request-start', 'api-request-e
 
 ---
 
+## 🗺️ Source Map 支持与配置
+
+在小程序中，报错堆栈的路径通常是各种虚拟路径（如 `appservice/pages/index.js`），这导致直接上传的 Source Map 无法被 Sentry 正确解析。
+
+SDK 内部已经为您解决了这个痛点：
+只要在 `Sentry.init` 时开启了 `enableSourceMap: true`（默认开启），SDK 会在报错时自动拦截并抹平各平台的虚拟路径，统一替换为标准前缀 `app:///`。
+
+您**只需要在打包上传 Source Map 时，确保配置的 `url-prefix` 为 `app:///` 即可**。
+
+**使用 sentry-cli 上传示例：**
+
+```bash
+sentry-cli releases files "your-project-release-id" upload-sourcemaps ./dist \
+  --url-prefix "app:///" \
+  --ext .js --ext .map
+```
+
+*(注：在微信开发者工具上传代码时，请**务必关闭**工具自带的“ES6转ES5”和“代码压缩”功能，将这些工作交给 Webpack/Vite 等构建工具，以防行列号错位。)*
+
+---
+
+## 💬 用户反馈 (User Feedback)
+
+在 Web 环境中，Sentry 提供了一个现成的 `showReportDialog()` 弹窗。但在小程序环境中没有 DOM 无法直接渲染该组件，因此 `showReportDialog()` 已被**废弃**。
+
+请您**自行实现一个原生小程序表单（或弹窗）**来收集用户的反馈信息，然后调用 `Sentry.captureFeedback()` 提交到 Sentry 后台：
+
+```javascript
+// 当发生错误，或者用户主动点击“反馈”按钮时，展示您自己画的表单：
+const userMessage = '页面卡住了，点什么都没反应';
+const userName = '张三';
+const userEmail = 'zhangsan@example.com';
+
+// 将收集到的反馈发送给 Sentry
+Sentry.captureFeedback({
+  message: userMessage,
+  name: userName,
+  email: userEmail,
+  // 选填：如果您想把这个反馈和某个具体的错误事件关联起来：
+  // associatedEventId: 'abc123xyz...'
+});
+```
+
+---
+
+## 📦 主包体积优化 (0KB 主包占用方案)
+
+小程序的“主包体积”非常宝贵（通常限制在 2MB 以内）。`sentry-miniapp` 由于集成了完整的 `@sentry/core` 核心引擎和多端适配，原始体积约在 200KB 左右。
+
+如果您非常在意主包体积，**强烈建议使用平台提供的「分包异步化」或「动态加载」特性**，将 SDK 的体积完全转移到分包中。
+
+### 方案 A：微信 / 支付宝小程序（推荐）
+
+微信和支付宝等平台原生支持[分包异步化](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html)。
+
+**具体操作步骤：**
+
+1. 将 `sentry-miniapp` 的 npm 包或者构建后的文件放入您的某个分包目录中（例如 `subpackageA`）。
+2. 在您的 `app.js` 顶部，使用 `require.async` 异步懒加载 SDK 并进行初始化：
+
+```javascript
+// app.js
+App({
+  onLaunch() {
+    // 异步加载分包中的 sentry
+    require.async('./subpackageA/sentry-miniapp.js').then((Sentry) => {
+      Sentry.init({
+        dsn: 'https://xxxxxxxx@sentry.io/12345',
+        // ...其他配置
+      });
+      console.log('Sentry 异步加载并初始化成功');
+    }).catch(err => {
+      console.error('Sentry 加载失败', err);
+    });
+  }
+});
+```
+
+*通过这种方式，Sentry 的 200KB 体积将**全部算入 `subpackageA` 的分包体积**，主包占用为 0！*
+
+### 方案 B：其他小程序平台（字节、百度等）
+
+对于暂不支持 `require.async` 的平台，您可以采用**分包预下载 + API 动态加载**的方式：
+
+1. 同样将 SDK 放入分包（如 `subpackageA`）。
+2. 在 `app.js` 中使用平台原生的分包加载 API 先下载分包，下载成功后再通过同步 `require` 引入 SDK：
+
+```javascript
+// 以字节小程序为例
+App({
+  onLaunch() {
+    const loadTask = tt.loadSubpackage({
+      name: 'subpackageA',
+      success: () => {
+        // 分包加载成功后，就可以安全地 require 了
+        const Sentry = require('./subpackageA/sentry-miniapp.js');
+        Sentry.init({ dsn: '...' });
+      }
+    });
+  }
+});
+```
+
+*注：如果您使用的是 Taro / uni-app 等跨端框架，可以直接使用 `import('sentry-miniapp')` 动态导入语法，框架会在编译时自动抹平各端差异。*
+
+---
+
 ## ❓ 常见问题 (FAQ)
 
 ### 1. 初始化后无法自动上报异常，必须在 `onError` 中手动调 API 吗？

package/dist/sentry-miniapp.cjs.js

@@ -4938,7 +4938,7 @@ function addBreadcrumb(breadcrumb, hint) {
   }
   isolationScope.addBreadcrumb(finalBreadcrumb, maxBreadcrumbs);
 }
-const SDK_VERSION = "1.2.0";
+const SDK_VERSION = "1.3.1";
 const SDK_NAME = "sentry.javascript.miniapp";
 const getSDK = () => {
   let currentSdk = {
@@ -5140,15 +5140,16 @@ function createMiniappTransport(options) {
   }
   return createTransport(options, makeRequest);
 }
-const MAX_OFFLINE_CACHE_SIZE = 30;
+const DEFAULT_OFFLINE_CACHE_SIZE = 30;
 const OFFLINE_STORE_KEY = "sentry_offline_store";
-function createMiniappOfflineStore(_options) {
+function createMiniappOfflineStore(options) {
+  const maxCacheSize = options.offlineCacheLimit || DEFAULT_OFFLINE_CACHE_SIZE;
   return {
     push: (env) => __async(null, null, function* () {
       try {
         const store = getStore();
         store.push(env);
-        if (store.length > MAX_OFFLINE_CACHE_SIZE) {
+        if (store.length > maxCacheSize) {
           store.shift();
         }
         setStore(store);
@@ -5160,7 +5161,7 @@ function createMiniappOfflineStore(_options) {
       try {
         const store = getStore();
         store.unshift(env);
-        if (store.length > MAX_OFFLINE_CACHE_SIZE) {
+        if (store.length > maxCacheSize) {
           store.pop();
         }
         setStore(store);
@@ -5225,6 +5226,7 @@ class MiniappClient extends Client {
         }));
         if (options.enableOfflineCache !== false) {
           return makeOfflineTransport(() => baseTransport)(__spreadProps(__spreadValues({}, transportOptions), {
+            offlineCacheLimit: options.offlineCacheLimit,
             createStore: createMiniappOfflineStore,
             flushAtStartup: true
             // 启动时自动重试发送
@@ -5319,29 +5321,14 @@ class MiniappClient extends Client {
     }
   }
   /**
-   * Show a report dialog to the user to send feedback to a specific event.
-   * 向用户显示报告对话框以将反馈发送到特定事件。
-   * 注意：小程序环境使用模态对话框模拟此功能
-   *
-   * @param options Set individual options for the dialog
-   */
-  showReportDialog(options = {}) {
-    const showModal = sdk().showModal;
-    if (showModal) {
-      showModal({
-        title: options.title || "错误反馈",
-        content: options.subtitle || "应用遇到了一个错误，是否要发送错误报告？",
-        confirmText: "发送",
-        cancelText: "取消",
-        success: (res) => {
-          if (res.confirm && options.onLoad) {
-            options.onLoad();
-          }
-        }
-      });
-    } else {
-      console.warn("sentry-miniapp: showModal is not available in current miniapp platform", options);
-    }
+   * @deprecated Miniapp environment does not support Sentry's default HTML report dialog.
+   * Please implement your own UI form to collect user feedback (name, email, comments)
+   * and use `Sentry.captureFeedback()` to submit it to Sentry.
+   */
+  showReportDialog(_options = {}) {
+    console.warn(
+      "[sentry-miniapp] showReportDialog is deprecated and does nothing. Please build your own UI and use `Sentry.captureFeedback()` instead."
+    );
   }
   /**
    * Capture feedback using the new feedback API.
@@ -5555,13 +5542,13 @@ const _TryCatch = class _TryCatch {
   setupOnce() {
     const global2 = globalThis;
     if (global2.setTimeout) {
-      fill(global2, "setTimeout", this._wrapTimeFunction.bind(this));
+      fill$1(global2, "setTimeout", this._wrapTimeFunction.bind(this));
     }
     if (global2.setInterval) {
-      fill(global2, "setInterval", this._wrapTimeFunction.bind(this));
+      fill$1(global2, "setInterval", this._wrapTimeFunction.bind(this));
     }
     if (global2.requestAnimationFrame) {
-      fill(global2, "requestAnimationFrame", this._wrapRAF.bind(this));
+      fill$1(global2, "requestAnimationFrame", this._wrapRAF.bind(this));
     }
   }
 };
@@ -5642,7 +5629,7 @@ function wrap$1(fn, options = {}, before) {
   }
   return sentryWrapped;
 }
-function fill(source, name, replacementFactory) {
+function fill$1(source, name, replacementFactory) {
   if (!(name in source)) {
     return;
   }
@@ -6665,13 +6652,173 @@ let PerformanceIntegration = _PerformanceIntegration;
 const performanceIntegration = (options) => {
   return () => new PerformanceIntegration(options);
 };
+const _RewriteFrames = class _RewriteFrames {
+  constructor(options = {}) {
+    this.name = _RewriteFrames.id;
+    this._prefix = options.prefix || "app:///";
+  }
+  /**
+   * @inheritDoc
+   */
+  setupOnce() {
+  }
+  /**
+   * @inheritDoc
+   */
+  processEvent(event) {
+    if (event.exception && event.exception.values) {
+      event.exception.values.forEach((exception) => {
+        if (exception.stacktrace && exception.stacktrace.frames) {
+          exception.stacktrace.frames.forEach((frame) => {
+            if (frame.filename) {
+              frame.filename = this._normalizeFilename(frame.filename);
+            }
+          });
+        }
+      });
+    }
+    return event;
+  }
+  /**
+   * Normalizes a filename from various miniapp platforms
+   */
+  _normalizeFilename(filename) {
+    let normalized = filename;
+    normalized = normalized.replace(/^(appservice|app-service|WAService)\//i, "").replace(/^https?:\/\/[^/]+\//i, "").replace(/^[a-z]+:\/\//i, "").replace(/^\//, "");
+    if (normalized.startsWith(this._prefix)) {
+      return normalized;
+    }
+    return `${this._prefix}${normalized}`;
+  }
+};
+_RewriteFrames.id = "RewriteFrames";
+let RewriteFrames = _RewriteFrames;
+function fill(source, name, replacementFactory) {
+  if (!(name in source)) {
+    return;
+  }
+  const original = source[name];
+  const wrapped = replacementFactory(original);
+  if (typeof wrapped === "function") {
+    try {
+      wrapped.prototype = wrapped.prototype || {};
+      wrapped.prototype.constructor = wrapped;
+    } catch (_Oo) {
+    }
+  }
+  source[name] = wrapped;
+}
+const _NetworkBreadcrumbs = class _NetworkBreadcrumbs {
+  constructor(options = {}) {
+    this.name = _NetworkBreadcrumbs.id;
+    this._traceNetworkBody = !!options.traceNetworkBody;
+  }
+  /**
+   * @inheritDoc
+   */
+  setupOnce() {
+    const miniappSdk = sdk();
+    if (miniappSdk && typeof miniappSdk.request === "function") {
+      fill(miniappSdk, "request", this._createRequestWrapper.bind(this));
+    }
+    if (miniappSdk && typeof miniappSdk.httpRequest === "function") {
+      fill(miniappSdk, "httpRequest", this._createRequestWrapper.bind(this));
+    }
+  }
+  /**
+   * Wraps the miniapp request API to capture breadcrumbs
+   */
+  _createRequestWrapper(originalRequest) {
+    const traceNetworkBody = this._traceNetworkBody;
+    return function(options) {
+      if (!options || typeof options !== "object") {
+        return originalRequest.call(this, options);
+      }
+      const url = options.url || "";
+      const client = getClient();
+      let dsnUrl = "";
+      if (client) {
+        const dsn = client.getOptions().dsn;
+        if (dsn) {
+          try {
+            const dsnMatch = dsn.match(/^(?:https?:\/\/)?(?:[^@\n]+@)?([^:/\n]+)/i);
+            if (dsnMatch && dsnMatch[1]) {
+              dsnUrl = dsnMatch[1];
+            }
+          } catch (e) {
+          }
+        }
+      }
+      if (typeof url === "string") {
+        const isSentryRequest = dsnUrl && url.indexOf(dsnUrl) !== -1 || url.indexOf("sentry.io") !== -1;
+        if (isSentryRequest) {
+          return originalRequest.call(this, options);
+        }
+      }
+      const method = (options.method || "GET").toUpperCase();
+      const requestData = options.data;
+      const breadcrumbData = {
+        url,
+        method
+      };
+      if (traceNetworkBody && requestData) {
+        try {
+          breadcrumbData["request_body"] = typeof requestData === "string" ? requestData : JSON.stringify(requestData);
+        } catch (e) {
+          breadcrumbData["request_body"] = "[Cannot serialize request body]";
+        }
+      }
+      const originalSuccess = options.success;
+      const originalFail = options.fail;
+      options.success = function(...args) {
+        const res = args[0] || {};
+        const statusCode = res.statusCode || res.status;
+        breadcrumbData["status_code"] = statusCode;
+        if (traceNetworkBody && res.data) {
+          try {
+            breadcrumbData["response_body"] = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
+          } catch (e) {
+            breadcrumbData["response_body"] = "[Cannot serialize response body]";
+          }
+        }
+        addBreadcrumb({
+          type: "http",
+          category: "xhr",
+          data: breadcrumbData,
+          level: statusCode >= 400 ? "warning" : "info"
+        });
+        if (typeof originalSuccess === "function") {
+          return originalSuccess.apply(this, args);
+        }
+      };
+      options.fail = function(...args) {
+        const err = args[0] || {};
+        breadcrumbData["error"] = err.errMsg || err.errorMessage || "Network request failed";
+        addBreadcrumb({
+          type: "http",
+          category: "xhr",
+          data: breadcrumbData,
+          level: "error"
+        });
+        if (typeof originalFail === "function") {
+          return originalFail.apply(this, args);
+        }
+      };
+      return originalRequest.call(this, options);
+    };
+  }
+};
+_NetworkBreadcrumbs.id = "NetworkBreadcrumbs";
+let NetworkBreadcrumbs = _NetworkBreadcrumbs;
 const index = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   Dedupe,
   GlobalHandlers,
   HttpContext,
   LinkedErrors,
+  NetworkBreadcrumbs,
   PerformanceIntegration,
+  RewriteFrames,
   Router,
   System,
   TryCatch,
@@ -6707,6 +6854,10 @@ function init(options = {}) {
     stackParser: () => [],
     transport: options.transport
   });
+  if (opts.enableSourceMap !== false) {
+    opts.integrations.push(new RewriteFrames());
+  }
+  opts.integrations.push(new NetworkBreadcrumbs({ traceNetworkBody: opts.traceNetworkBody }));
   setContext("miniapp", {
     platform: appName,
     environment: "miniapp"
@@ -6729,13 +6880,10 @@ function init(options = {}) {
   initAndBind(MiniappClient, opts);
   return getCurrentScope().getClient();
 }
-function showReportDialog(options = {}) {
-  const client = getCurrentScope().getClient();
-  if (client) {
-    client.showReportDialog(options);
-  } else {
-    console.warn("sentry-miniapp: No client available for showReportDialog");
-  }
+function showReportDialog(_options = {}) {
+  console.warn(
+    "[sentry-miniapp] showReportDialog is deprecated and does nothing. Please build your own UI and use `Sentry.captureFeedback()` instead."
+  );
 }
 function wrap(fn) {
   return (function(...args) {