@evertro/monitor-taro

Evertro Monitor Taro 统一入口 — 小程序 + H5 自动适配

概述

本包是面向 Taro 框架的 SDK 统一入口，自动检测运行环境（微信小程序 / H5），加载对应的平台插件和传输层。是大多数项目的直接使用入口。

核心价值： 一次初始化，自动适配小程序和 H5 两种环境，业务代码无需关心底层平台差异。

安装

pnpm add @evertro/monitor-taro

快速开始

// app.ts — Taro 应用入口
import { EvertroMonitor } from '@evertro/monitor-taro';

EvertroMonitor.init({
  appId: 'domus_miniapp',
  dsn: 'https://monitor-api.example.com/v1/report',
  environment: 'production',
  debug: false,
});

// 设置用户信息（登录后调用）
EvertroMonitor.setUser({
  userId: '100',
  isLogin: true,
  sessionId: 'auto-generated',
});

模块说明

monitor.ts — EvertroMonitor 主类

SDK 的顶层 API 入口，负责组装引擎、插件和传输层。

初始化流程

EvertroMonitor.init(config)
  │
  ├── 1. 检测运行平台（isWeapp() / isH5()）
  │
  ├── 2. 获取设备信息
  │     ├── 小程序: wx.getSystemInfoSync()
  │     └── H5: navigator.userAgent 解析
  │
  ├── 3. 创建引擎
  │     └── new CollectorEngine(config)
  │
  ├── 4. 加载平台插件
  │     ├── 小程序环境:
  │     │   ├── MiniappErrorPlugin
  │     │   ├── MiniappBreadcrumbPlugin
  │     │   ├── MiniappPerformancePlugin
  │     │   ├── MiniappNetworkPlugin
  │     │   └── MiniappWhiteScreenPlugin
  │     │
  │     └── H5 环境:
  │         ├── WebErrorPlugin
  │         ├── WebBreadcrumbPlugin
  │         ├── WebPerformancePlugin
  │         ├── WebNetworkPlugin
  │         └── WebWhiteScreenPlugin
  │
  ├── 5. 创建传输层
  │     ├── 小程序: WeappTransport
  │     └── H5: H5Transport
  │
  ├── 6. 创建上报队列
  │     └── new ReportQueue(transport, config, ...)
  │
  ├── 7. 连接引擎到上报队列
  │     └── engine.setReportCallback(queue.enqueue)
  │
  ├── 8. 初始化引擎（启动所有插件）
  │     └── engine.init()
  │
  └── 9. 启动上报队列定时器
        └── queue.start()

公开 API

| 方法 | 描述 | |------|------| | EvertroMonitor.init(config) | 初始化 SDK（只能调用一次） | | EvertroMonitor.setUser(userContext) | 设置/更新用户信息 | | EvertroMonitor.addBreadcrumb(crumb) | 手动添加操作链路节点 | | EvertroMonitor.captureException(error) | 手动上报异常 | | EvertroMonitor.captureMessage(message) | 手动上报消息 | | EvertroMonitor.flush() | 立即 flush 队列（app.onHide 时调用） | | EvertroMonitor.destroy() | 销毁 SDK |

使用示例

import { EvertroMonitor } from '@evertro/monitor-taro';

// 初始化
EvertroMonitor.init({
  appId: 'domus_miniapp',
  dsn: 'https://monitor-api.example.com/v1/report',
  environment: 'uat',
  debug: true,
  sampleRate: 1.0,
  reportBatchSize: 5,
  reportInterval: 10000,
  maxRetries: 3,
  beforeSend: (event) => {
    console.log('[Monitor Event]', event.eventId, event.eventName, event);
    return event; // 返回 null 则丢弃
  },
  ignoreErrors: ['ResizeObserver loop'],
  sensitiveFields: ['token', 'password', 'phone'],
});

// 登录后设置用户
EvertroMonitor.setUser({
  userId: userInfo.id,
  isLogin: true,
  sessionId: 'xxx',
  projectId: '123',
});

// 手动上报异常
try {
  riskyOperation();
} catch (e) {
  EvertroMonitor.captureException(e);
}

// 手动上报消息
EvertroMonitor.captureMessage('用户完成了支付流程');

// 手动添加操作链路
EvertroMonitor.addBreadcrumb({
  type: 'custom',
  category: 'payment',
  message: '用户点击了支付按钮',
  level: 'info',
});

// App.onHide 时 flush
EvertroMonitor.flush();

platform.ts — 平台检测

import { isWeapp, isH5 } from '@evertro/monitor-taro';

isWeapp(); // true — 微信/抖音小程序环境
isH5();    // true — H5 浏览器环境

检测逻辑：

function isWeapp(): boolean {
  return typeof wx !== 'undefined' && typeof wx.getSystemInfoSync === 'function';
}

function isH5(): boolean {
  return typeof window !== 'undefined' && typeof document !== 'undefined';
}

deviceContext.ts — 设备信息获取

根据运行平台获取设备信息，填充 DeviceContext。

小程序环境：

const info = wx.getSystemInfoSync();
// {
//   platform: 'weapp',
//   brand: 'iPhone',
//   model: 'iPhone 13',
//   system: 'iOS 15.4',
//   sdkVersion: '2.25.0',
//   screenWidth: 375,
//   screenHeight: 812,
//   pixelRatio: 3,
//   networkType: 'wifi',  // 通过 wx.getNetworkType 获取
// }

H5 环境：

// 解析 navigator.userAgent
// {
//   platform: 'h5',
//   browserName: 'Chrome',
//   browserVersion: '120.0.0',
//   system: 'macOS 14.0',
//   screenWidth: 1920,
//   screenHeight: 1080,
//   pixelRatio: 2,
// }

errorBoundary.tsx — React 错误边界组件

为 Taro React 应用提供的错误边界组件，捕获组件树中的渲染错误。

import { EvertroErrorBoundary } from '@evertro/monitor-taro';

// 包裹整个应用或特定区域
<EvertroErrorBoundary fallback={<View>页面出错了</View>}>
  <MyApp />
</EvertroErrorBoundary>

工作原理：

组件渲染错误
  └── React componentDidCatch(error, errorInfo)
        ├── 提取 componentStack
        ├── report({
        │     type: 'react_error',
        │     message: error.message,
        │     stack: error.stack,
        │     componentStack: errorInfo.componentStack,
        │     priority: BATCH,
        │   })
        └── 渲染 fallback UI

配置参数完整列表

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | 必填 | 应用标识 | | dsn | string | 必填 | 上报地址 | | environment | string | 'production' | 环境标识 | | release | string | — | 版本号 | | sampleRate | number | 1.0 | 采样率（0~1），P0 事件不受限 | | debug | boolean | false | 调试模式（控制台打印） | | enableErrorCapture | boolean | true | 启用错误捕获 | | enableWhiteScreen | boolean | true | 启用白屏检测 | | enableBreadcrumbs | boolean | true | 启用操作链路 | | enablePerformance | boolean | true | 启用性能采集 | | enableNetworkMonitor | boolean | true | 启用网络监控 | | breadcrumbsLimit | number | 30 | 操作链路上限 | | whiteScreenTimeout | number | 5000 | 白屏检测超时 ms | | reportBatchSize | number | 10 | 批量上报条数 | | reportInterval | number | 10000 | 定时上报间隔 ms | | maxRetries | number | 3 | 上报重试次数 | | maxCacheSize | number | 100 | 离线缓存上限 | | offlineMaxBytes | number | 512000 | 离线缓存字节上限 | | beforeSend | function | — | 上报前钩子（返回 null 丢弃） | | sensitiveFields | string[] | ['token','password','phone','idCard'] | 脱敏字段 | | ignoreErrors | (string|RegExp)[] | [] | 忽略的错误 |

依赖关系

@evertro/monitor-types
@evertro/monitor-core
@evertro/monitor-transport
@evertro/monitor-miniapp    ←── 小程序平台插件
@evertro/monitor-web        ←── H5 平台插件
        ↓
@evertro/monitor-taro       ←── 统一入口

导出一览

export { EvertroMonitor } from './monitor';
export { EvertroErrorBoundary } from './errorBoundary';
export { isWeapp, isH5 } from './platform';