@xfshz/xr-monitor-sdk

xr-monitor-sdk

前端监控 SDK，专为 Vue 3 定制的高稳定性、低性能损耗监控脚本。 实时捕获、清洗、聚合本地异常，并以非阻塞方式上报到云端。

文档导航

安装

npm install xr-monitor-sdk

或通过 CDN（构建出单文件脚本，全局变量 XRMonitor）：

npm run build:cdn

<script src="https://你的域名/static/xr-monitor-sdk.min.js"></script>
<script>
  XRMonitor.init({ appId: 'your_project_id', env: 'prod' });
</script>

package.json 同时声明了 unpkg / jsdelivr 字段，发布到 npm 后可：

<script src="https://unpkg.com/xr-monitor-sdk@1.0.0/dist/xr-monitor-sdk.min.js"></script>

快速使用

import monitor from 'xr-monitor-sdk';

// 1. 初始化（必填 appId / env；上报域名用 baseUrl，见下表）
monitor.init({
  appId: 'your_project_id',
  env: 'prod',
  version: '1.0.0',
  sampleRate: 0.1,
  // 监控服务根地址，自动拼接 /monitor-server/api/monitor/report 与 /monitor-server/api/monitor/manual-report
  baseUrl: 'https://monitor-api.example.com',
  isBusinessError: (res) => res.code !== 200,
  // 返回 false 的接口不上报 API 异常（仍保留面包屑）
  shouldReportApi: (url, method) => !url.includes('/component/loadUiTab'),
});

// 2. 绑定 Vue 3 errorHandler（在 init 之后、app.mount 之前）
import { createApp } from 'vue';
import App from './App.vue';
const app = createApp(App);
monitor.bindVueErrorHandler(app);
app.mount('#app');

// 3. 登录后挂载用户上下文
monitor.setContext({ userId: '888', userLevel: 'VIP' });

// 4. 手动上报错误（默认立即 POST）
monitor.error(new Error('手动捕获的异常'), { customData: '...' });

// 5. 业务埋点（默认立即 POST）
monitor.info('用户进入支付页面', { payType: 'wechat' });

// 6. 手动批量上报（立即 POST，支持多条）
monitor.manualUpload([
  { eventName: 'enter_checkout', eventType: 'track', env: 'prod' },
  { eventName: 'custom_tag', eventType: 'custom', env: 'prod', severity: 'high' },
]);

// 7. 主动 flush 批量队列（仅自动采集链路）
monitor.flushReportQueue();

monitor.error / monitor.info 走手动上报接口并立即 POST（不进批量队列）。 自动采集（Error/Network/Performance/PV）仍走批量队列。 兼容参数提示：monitor.error/info 传 { immediate: false } 已废弃，不再改变发送行为。

配置项

完整类型见 src/core/types.ts 的 MonitorOptions。

上报接口

• POST /monitor-server/api/monitor/report
• 请求体：{ appId, events: [{ type, data }] }，type 为 error / performance / page_view。
• 完整字段定义见 product/OVERVIEW.md §2。

手动上报方法示例

手动链路走 manualReportUrl，调用即发；monitor.error/info 不进入自动批量队列。

import monitor from 'xr-monitor-sdk';

monitor.init({
  appId: 'your_project_id',
  env: 'prod',
  version: '1.2.3',
  baseUrl: 'https://log.example.com',
  // 可选：不传时默认拼接为 /monitor-server/api/monitor/manual-report
  manualReportUrl: 'https://log.example.com/monitor-server/api/monitor/manual-report',
});

// 1) 手动错误上报（内部会转成手动事件并立即发送）
monitor.error(new Error('支付请求失败'), {
  eventName: 'pay_submit_error',
  severity: 'high',
  payload: {
    orderId: 'A10086',
    payType: 'wechat',
  },
});

// 2) 业务埋点（内部会转成 track 事件并立即发送）
monitor.info('进入支付确认页', {
  eventName: 'enter_pay_confirm',
  payload: {
    from: 'checkout',
    couponUsed: true,
  },
});

// 3) 手动批量上报（一次请求多条 events）
monitor.manualUpload([
  {
    eventName: 'risk_check_start',
    eventType: 'track',
    description: '开始风控检查',
    payload: { orderId: 'A10086' },
    env: 'prod',
  },
  {
    eventName: 'risk_check_blocked',
    eventType: 'custom',
    description: '风控拦截',
    payload: { ruleId: 'RISK_001' },
    env: 'prod',
    severity: 'critical',
  },
]);

手动事件字段建议：

• eventType: error | track | custom
• severity: low | medium | high | critical（不传默认 low）
• 顶层请求体结构：{ appId, events }（appId 在顶层，不在每条 event 内重复）

开发命令

npm run dev          # 开发监听构建（带 sourcemap）
npm run debug        # 单次开发构建
npm run build        # 生产构建
npm run build:cdn    # 单文件 CDN 产物
npm run demo         # 构建 + 启动 demo 页（http://localhost:5175/demo/index.html）
npm run type-check   # TS 类型检查
npm run lint         # ESLint
npm run test         # Jest（11 套件 / 36 用例）

调试细节见 DEBUGGING.md。

当前实现状态

SDK 架构、Core、Reporter、ErrorPlugin、NetworkPlugin、PerformancePlugin、BehaviorPlugin、自动 PV、用户标识、上报体映射 已可用； 并已完成 ErrorPlugin Anti-Loop 补强、Error.stack 位置补全 与 Jest 单测覆盖（11 套件 / 36 用例）。 完整逐项状态见 ARCHITECTURE.md §5「实现现状」。