@monitor/sdk

前端监控平台的 Web SDK，对外提供统一的 init 能力，并在内部默认集成多种采集插件（错误、性能、白屏、网络、PV/UV），帮助你快速为项目接入前端监控。

本包只负责 采集与上报，配合后端 Ingest API 与监控后台使用效果最佳。

特性

• 🌐 统一事件模型：所有事件共用一套 envelope 字段（appId/env/release/pageUrl/sessionId 等）
• 🔌 插件化采集能力（默认启用）
  • 错误监控：error / unhandledrejection / resource error
  • 性能监控：FCP / LCP / CLS / LongTask / Navigation Timing
  • 白屏监控：延迟检测 + 多点采样 + 路由复检
  • PV/UV：基于 visitorId 的去重统计
  • 网络监控：fetch / XHR 拦截，请求耗时、状态码与失败采集
• 📦 内置队列与批量上报：支持按时间/条数阈值批量 flush
• 🎯 采样与脱敏：支持按事件类型采样、beforeSend 钩子与字段级脱敏

安装

使用 npm：

npm install @monitor/sdk

或使用 pnpm：

pnpm add @monitor/sdk

快速开始

在你的前端入口文件中初始化 SDK：

import { init } from '@monitor/sdk'

init({
  appId: 'your-app-id',
  endpoint: 'https://your-monitor-api.com',
  env: 'production',
  release: '1.0.0',
  appKey: 'your-app-key', // 可选，如服务端开启 appKey 鉴权则必填
  sampleRate: 0.2, // 默认采样率（非错误类事件）
})

初始化后，SDK 会默认安装以下插件：

• 错误监控插件
• 性能监控插件（Web Vitals）
• 白屏监控插件
• PageView/PV-UV 插件
• 网络请求监控插件

你也可以按需传入额外插件或关闭部分能力（具体可参考源码与注释）。

与后端配合使用

SDK 默认将事件批量上报到：

{endpoint}/v1/ingest/batch

请确保服务端已实现对应的 Ingest API，并根据需要开启：

• appId/appKey 鉴权
• 域名白名单
• SourceMap 上传与堆栈反解等能力

License

MIT