WebVitals Pro

专业的 Web Vitals 性能监控 SDK，提供实时性能追踪、错误监控和用户体验分析。

✨ 核心特性

• 🚨 错误监控 - 自动捕获 JavaScript 运行时错误、Promise 异常和资源加载错误，支持手动错误上报
• ⚡ 性能监控 - 追踪核心 Web 性能指标（FCP、LCP、FID/INP、CLS）和其他关键性能数据
• 🌐 接口监控 - 拦截并上报 fetch 和 XMLHttpRequest 请求，包括状态码、耗时和成功率
• 🔍 用户行为轨迹 - 记录用户交互为错误调试提供宝贵的上下文信息
• ⚙️ 灵活配置 - 通过钩子函数支持模块粒度控制和数据处理
• 🪶 轻量无侵入 - 专为最小化应用性能影响而设计

📦 安装

npm 安装

npm install webvitals-pro

CDN 引入

<!-- UMD 版本 -->
<script src="https://unpkg.com/webvitals-pro@latest/dist/index.js"></script>

<!-- ES Module 版本 -->
<script type="module">
  import WebVitalsPro from 'https://unpkg.com/webvitals-pro@latest/dist/index.esm.js';
</script>

🚀 快速开始

基础使用

在应用程序入口尽早初始化 SDK：

import monitor from 'webvitals-pro';

monitor.init({
  appId: 'YOUR_APP_ID', // 必需：应用程序唯一标识符
  serverUrl: 'http://localhost:3000/report', // 必需：后端上报接口地址
  release: '1.0.0', // 可选：当前应用版本号
  userId: 'user-123', // 可选：用户标识符
});

手动错误上报

try {
  // 可能抛出错误的代码
  throw new Error('出现了问题！');
} catch (error) {
  monitor.captureError(error);
}

自定义用户行为轨迹

monitor.addBreadcrumb({
  type: 'custom',
  timestamp: Date.now(),
  message: '用户点击了结账按钮',
});

📖 API 参考

monitor.init(options)

初始化监控 SDK，必须在其他 SDK 功能之前调用。

参数：

• appId (string, 必需) - 应用程序唯一标识符
• serverUrl (string, 必需) - 后端服务上报数据的 URL 地址
• userId (string, 可选) - 用户标识符
• release (string, 可选) - 应用版本号
• beforeSend (function, 可选) - 数据预处理钩子函数

monitor.captureError(error)

手动上报错误，适用于在 try...catch 块中捕获的错误。

monitor.addBreadcrumb(breadcrumb)

手动添加自定义用户行为轨迹，这些轨迹会包含在后续的错误报告中。

🔧 高级配置

beforeSend 钩子函数

monitor.init({
  appId: 'my-app',
  serverUrl: 'https://api.example.com/report',
  beforeSend: (data) => {
    // 过滤敏感信息
    if (data.type === 'error' && data.data.message.includes('password')) {
      return null; // 丢弃包含敏感信息的错误
    }

    // 添加自定义字段
    data.customField = 'additional-info';

    return data;
  },
});

📁 项目结构

webvitals-pro/
├── src/                  # SDK 源代码
│   ├── core/             # 核心模块：初始化、数据队列、用户行为轨迹管理
│   ├── modules/          # 监控模块：错误、性能、请求、监听器
│   ├── types/            # TypeScript 类型定义
│   └── index.ts          # SDK 主入口文件
├── dist/                 # 编译和打包输出
├── examples/             # 使用示例
└── ...

🛠️ 开发

构建项目

npm run build

运行测试

npm test

开发模式

npm run dev

📚 更多文档

• 架构设计文档 - 详细的技术实现和设计思路
• 示例代码 - 完整的使用示例

🤝 贡献

欢迎贡献代码！请先阅读 架构设计文档 了解项目结构。

📄 许可证

本项目基于 MIT 许可证开源 - 详见 LICENSE 文件。