前端监控SDK

一个功能完整的前端监控SDK，支持错误监控、性能监控和用户行为追踪。使用现代 Web API 构建，支持最新的性能指标。

功能特性

• ✅ 错误监控：自动捕获JavaScript错误、Promise错误、资源加载错误
• ✅ 性能监控：使用现代 PerformanceNavigationTiming API，支持 Web Vitals 指标
  • 基础指标：DNS、TCP、TLS、请求响应时间
  • 渲染指标：FP、FCP、LCP
  • 交互指标：FID、TTI
  • 稳定性指标：CLS
• ✅ 用户行为：点击事件、页面访问、路由导航追踪
• ✅ 数据上报：支持批量上报、采样控制、自动重试、超时控制
• ✅ TypeScript：完整的类型定义，支持现代 ES 模块
• ✅ 轻量级：无外部依赖，体积小
• ✅ 现代构建：使用 Rollup 构建，支持 ESM、CJS、UMD 格式

安装

npm install @ariel_jhy/frontend-monitor-sdk

快速开始

基础用法

import FrontendMonitor from '@ariel_jhy/frontend-monitor-sdk';

// 初始化SDK
const monitor = new FrontendMonitor({
  url: 'https://your-api.com/monitor/report',
  appId: 'your-app-id',
  userId: 'user-123', // 可选
  enableError: true,
  enablePerformance: true,
  enableBehavior: true,
  sampleRate: 1, // 采样率 0-1
  immediate: false, // 是否立即上报
  maxBatchSize: 10, // 批量上报最大数量
  reportDelay: 5000 // 上报延迟时间（ms）
});

// 启动监控
monitor.init();

手动上报

// 手动上报错误
monitor.reportError(new Error('Something went wrong'));
monitor.reportError('Error message');

// 手动上报行为
monitor.reportBehavior('click', { element: 'button#submit' });
monitor.reportBehavior('pageview', { page: '/home' });

// 立即上报所有数据
monitor.flush();

获取监控数据

// 获取错误列表
const errors = monitor.getErrors();

// 获取性能数据
const performance = monitor.getPerformance();

// 获取行为列表
const behaviors = monitor.getBehaviors();

更新配置

// 更新用户ID
monitor.setUserId('new-user-id');

// 更新配置
monitor.updateConfig({
  sampleRate: 0.5,
  immediate: true
});

配置选项

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | url | string | 是 | - | 数据上报接口地址 | | appId | string | 是 | - | 应用ID | | userId | string | 否 | - | 用户ID | | enableError | boolean | 否 | true | 是否启用错误监控 | | enablePerformance | boolean | 否 | true | 是否启用性能监控 | | enableBehavior | boolean | 否 | true | 是否启用用户行为监控 | | sampleRate | number | 否 | 1 | 采样率（0-1） | | immediate | boolean | 否 | false | 是否立即上报 | | maxBatchSize | number | 否 | 10 | 批量上报最大数量 | | reportDelay | number | 否 | 5000 | 上报延迟时间（ms） |

数据格式

错误数据

{
  "type": "error",
  "errorType": "javascript",
  "message": "Error message",
  "filename": "app.js",
  "lineno": 123,
  "colno": 45,
  "stack": "Error stack trace",
  "timestamp": 1234567890,
  "url": "https://example.com/page",
  "userAgent": "Mozilla/5.0..."
}

性能数据

{
  "type": "performance",
  "dns": 10,
  "tcp": 20,
  "tls": 15,
  "request": 100,
  "domParse": 50,
  "resourceLoad": 200,
  "firstPaint": 150,
  "firstContentfulPaint": 180,
  "largestContentfulPaint": 2500,
  "firstInputDelay": 50,
  "cumulativeLayoutShift": 0.1,
  "loadComplete": 500,
  "timeToInteractive": 3500,
  "timestamp": 1234567890,
  "url": "https://example.com/page"
}

性能指标说明：

• dns: DNS查询时间（ms）
• tcp: TCP连接时间（ms）
• tls: TLS协商时间（ms，HTTPS）
• request: 请求响应时间（ms）
• domParse: DOM解析时间（ms）
• resourceLoad: 资源加载时间（ms）
• firstPaint: 首次绘制时间（ms）
• firstContentfulPaint: 首次内容绘制时间（ms）
• largestContentfulPaint: 最大内容绘制时间（ms，Web Vitals）
• firstInputDelay: 首次输入延迟（ms，Web Vitals）
• cumulativeLayoutShift: 累积布局偏移（Web Vitals）
• loadComplete: 页面完全加载时间（ms）
• timeToInteractive: 可交互时间（ms）

行为数据

{
  "type": "behavior",
  "action": "click",
  "element": "button#submit",
  "timestamp": 1234567890,
  "url": "https://example.com/page"
}

开发

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建生产版本
npm run build

# 类型检查
npm run type-check

构建产物

• dist/index.cjs.js - CommonJS 格式
• dist/index.esm.js - ES 模块格式（推荐）
• dist/index.umd.js - UMD 格式，可在浏览器直接使用
• dist/index.d.ts - TypeScript 类型定义文件

浏览器支持

• Chrome/Edge 51+（支持 PerformanceNavigationTiming）
• Firefox 45+（支持 PerformanceNavigationTiming）
• Safari 11+（支持 PerformanceNavigationTiming）

降级支持：

• 对于不支持现代 Performance API 的浏览器，SDK 会自动降级到 performance.timing API
• Web Vitals 指标（LCP、FID、CLS）需要浏览器支持 PerformanceObserver

技术栈

• 构建工具: Rollup（替代 Webpack，更适合库开发）
• 语言: TypeScript 5.3+
• 目标: ES2020
• 性能 API: PerformanceNavigationTiming、PerformanceObserver

注意事项

1. 确保上报接口支持CORS或使用JSONP
2. 建议设置合理的采样率以控制上报量
3. 页面卸载时会自动上报剩余数据
4. 支持SPA应用的路由监控
5. Web Vitals 指标在页面可见性变化时计算，确保数据准确性
6. 使用 sendBeacon API 优先上报，失败时自动降级到 fetch

License

MIT