webvitals-pro/README.md

Professional Web Vitals monitoring SDK with real-time performance tracking, error monitoring, and user experience analytics.

# WebVitals Pro

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

## ✨ 核心特性

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

## 📦 安装

### npm 安装

```bash
npm install webvitals-pro
```

### CDN 引入

```html
<!-- 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：

```typescript
import monitor from 'webvitals-pro';

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

### 手动错误上报

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

### 自定义用户行为轨迹

```typescript
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 钩子函数

```typescript
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/             # 使用示例
└── ...
```

## 🛠️ 开发

### 构建项目

```bash
npm run build
```

### 运行测试

```bash
npm test
```

### 开发模式

```bash
npm run dev
```

## 📚 更多文档

- [架构设计文档](./ARCHITECTURE.md) - 详细的技术实现和设计思路
- [示例代码](./examples/) - 完整的使用示例

## 🤝 贡献

欢迎贡献代码！请先阅读 [架构设计文档](./ARCHITECTURE.md) 了解项目结构。

## 📄 许可证

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