web-performance-monitor-sdk/README.md

A modern, lightweight performance monitoring SDK for web applications. Monitor Core Web Vitals (LCP, FCP, FID, CLS, TTFB) with sendBeacon support.

# Performance Monitor

一个现代化的、轻量级的Web应用性能监控SDK，专注于现代浏览器，提供简洁易用的API。

## 特性

- 🚀 **现代化设计** - 专为现代浏览器设计（Chrome、Safari、Firefox、Edge），代码简洁高效
- 📊 **核心性能指标** - 监控FCP、LCP、CLS、FID、TTFB等Core Web Vitals
- 🔧 **灵活配置** - 支持多种输出方式：console、sendBeacon、fetch、自定义
- 🐛 **错误监控** - 可选的JavaScript错误和资源加载错误监控
- 📦 **轻量级** - 无外部依赖，体积小巧
- 🎯 **TypeScript支持** - 完整的类型定义
- 🔍 **调试友好** - 内置调试模式，便于开发调试
- 🌐 **自动数据增强** - 自动采集设备信息、网络信息、资源加载时间等
- 🔌 **通用适配** - 适用于任何Web应用，无特定框架依赖

## 安装

```bash
npm install performance-monitor
```

## 快速开始

### 基础使用

```javascript
import PerformanceMonitor from 'performance-monitor';

// 最简单的使用方式 - 输出到控制台
const monitor = new PerformanceMonitor({
  output: 'console',
  debug: true
});
```

### 发送到服务器

```javascript
// 使用sendBeacon发送数据
const monitor = new PerformanceMonitor({
  output: 'sendBeacon',
  endpoint: 'https://your-api.com/performance',
  sampleRate: 0.1 // 10%采样率
});

// 使用fetch发送数据
const monitor = new PerformanceMonitor({
  output: 'fetch',
  endpoint: 'https://your-api.com/performance'
});
```

### 自定义输出

```javascript
const monitor = new PerformanceMonitor({
  output: 'custom',
  customReporter: (metrics) => {
    // 自定义处理逻辑
    console.log('Custom metrics:', metrics);
    // 发送到你的分析平台
    analytics.track('performance', metrics);
  }
});
```

### 启用错误监控

```javascript
const monitor = new PerformanceMonitor({
  output: 'console',
  enableErrorTracking: true,
  debug: true
});
```

## 配置选项

| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `output` | `'console' \| 'sendBeacon' \| 'fetch' \| 'custom'` | `'console'` | 输出方式 |
| `endpoint` | `string` | - | 数据发送的URL端点 |
| `customReporter` | `function` | - | 自定义输出函数 |
| `enableErrorTracking` | `boolean` | `false` | 是否启用错误监控 |
| `enableResourceTiming` | `boolean` | `false` | 是否启用资源监控 |
| `sampleRate` | `number` | `1` | 采样率 (0-1) |
| `debug` | `boolean` | `false` | 是否启用调试模式 |

## API

### PerformanceMonitor

主要的监控类。

#### 构造函数

```typescript
new PerformanceMonitor(config?: PerformanceMonitorConfig)
```

#### 方法

##### `getMetrics(): PerformanceMetrics`

获取当前收集的性能指标。

```javascript
const metrics = monitor.getMetrics();
console.log(metrics);
// 输出: { fcp: 1200, lcp: 2500, fid: 50, cls: 0.05, ttfb: 300 }
```

##### `getDetailedMetrics(): Record<string, MetricDetail>`

获取详细的性能指标信息，包括评分和时间戳。

```javascript
const detailedMetrics = monitor.getDetailedMetrics();
console.log(detailedMetrics);
// 输出: {
//   fcp: { value: 1200, score: 'good', timestamp: 1640995200000 },
//   lcp: { value: 2500, score: 'good', timestamp: 1640995201000 }
// }
```

##### `getErrorCount(): number`

获取错误统计数量。

```javascript
const errorCount = monitor.getErrorCount();
console.log(`Total errors: ${errorCount}`);
```

##### `reportMetrics(): void`

手动报告当前收集的所有性能指标。

```javascript
monitor.reportMetrics();
```

##### `disconnect(): void`

停止性能监控。

```javascript
monitor.disconnect();
```

##### `isReady(): boolean`

检查监控器是否已初始化。

```javascript
if (monitor.isReady()) {
  console.log('Performance monitoring is active');
}
```

##### `updateConfig(newConfig: Partial<PerformanceMonitorConfig>): void`

更新配置。

```javascript
monitor.updateConfig({
  debug: true,
  sampleRate: 0.5
});
```

## 性能指标说明

### FCP (First Contentful Paint)
首次内容绘制时间，测量页面首次绘制文本、图像或非白色背景的时间。

- **Good**: ≤ 1.8s
- **Needs Improvement**: 1.8s - 3.0s
- **Poor**: > 3.0s

### LCP (Largest Contentful Paint)
最大内容绘制时间，测量页面最大内容元素渲染完成的时间。

- **Good**: ≤ 2.5s
- **Needs Improvement**: 2.5s - 4.0s
- **Poor**: > 4.0s

### FID (First Input Delay)
首次输入延迟，测量用户首次与页面交互到浏览器响应该交互的时间。

- **Good**: ≤ 100ms
- **Needs Improvement**: 100ms - 300ms
- **Poor**: > 300ms

### CLS (Cumulative Layout Shift)
累积布局偏移，测量页面加载过程中意外布局偏移的程度。

- **Good**: ≤ 0.1
- **Needs Improvement**: 0.1 - 0.25
- **Poor**: > 0.25

### TTFB (Time to First Byte)
首字节时间，测量从请求页面到接收到第一个字节的时间。

- **Good**: ≤ 800ms
- **Needs Improvement**: 800ms - 1.8s
- **Poor**: > 1.8s

## 浏览器支持

- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+

需要支持以下API：
- PerformanceObserver
- PerformanceEntry
- sendBeacon (可选)
- fetch (可选)

## 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 类型检查
npm run type-check

# 代码检查
npm run lint

# 测试
npm test
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 更新日志

### v2.0.0
- 完全重构，移除hack代码
- 专注现代浏览器支持
- 简化API设计
- 添加TypeScript支持
- 支持多种输出方式
- 添加错误监控功能