my-performance-sdk/README.md

前端性能监控SDK，支持FCP、LCP、TBT、TTI和内存泄漏监控

# my-performance-sdk

> 前端性能监控SDK，支持FCP、LCP、TBT、TTI、内存泄漏和能耗监控

## 功能特性
- 自动采集核心Web Vitals（FCP、LCP、TBT、TTI等）
- 内存泄漏趋势检测
- 设备能耗监控（电池状态、CPU使用率等）
- 支持自定义数据上报/处理
- 支持npm集成，开箱即用
- 支持自定义上报接口和上报频率

## 安装

```bash
npm install my-performance-sdk
```

或

```bash
yarn add my-performance-sdk
```

## 快速开始

### 1. 在项目入口文件中引入并初始化

```js
import { initPerformanceSDK } from 'my-performance-sdk';

const sdk = initPerformanceSDK({
  reportUrl: 'https://your-server.com/perf-report', // 可选，数据上报接口
  reportInterval: 30000, // 可选，上报间隔，单位ms
  enableMemoryMonitoring: true, // 可选，是否启用内存监控
  enableWebVitals: true, // 可选，是否启用Web Vitals监控
  enablePowerMonitoring: true, // 可选，是否启用能耗监控
  onData: (data) => {
    // 可选，收到每次采集的数据时的回调
    console.log('性能数据:', data);
  }
});
```

### 2. 手动获取或上报性能数据

```js
import { getPerformanceMetrics, collectAndReport } from 'my-performance-sdk';

const metrics = getPerformanceMetrics();
console.log(metrics);

// 手动采集并上报一次
collectAndReport();
```

### 3. 停止/销毁SDK

```js
import { destroyPerformanceSDK } from 'my-performance-sdk';

destroyPerformanceSDK();
```

## API 说明

### 初始化
```ts
initPerformanceSDK(options?: PerformanceSDKOptions): PerformanceSDK
```
- `options` 配置项：
  - `autoStart` 是否自动开始监控，默认true
  - `reportUrl` 数据上报接口
  - `reportInterval` 上报间隔（ms），默认30000
  - `enableMemoryMonitoring` 是否启用内存监控，默认true
  - `enableWebVitals` 是否启用Web Vitals监控，默认true
  - `enablePowerMonitoring` 是否启用能耗监控，默认true
  - `onData` 每次采集到数据时的回调

### 获取SDK实例
```ts
getPerformanceSDK(): PerformanceSDK | null
```

### 获取当前性能指标
```ts
getPerformanceMetrics(): PerformanceMetrics
```

### 手动采集并上报
```ts
collectAndReport(): void
```

### 销毁SDK
```ts
destroyPerformanceSDK(): void
```

## 性能指标说明
- **FCP** (First Contentful Paint)：首次内容绘制时间
- **LCP** (Largest Contentful Paint)：最大内容绘制时间
- **TBT** (Total Blocking Time)：总阻塞时间
- **TTI** (Time to Interactive)：可交互时间
- **memory**：内存使用情况（仅支持部分浏览器）
- **loadTime**：页面加载总耗时
- **domContentLoaded**：DOM内容加载耗时
- **powerConsumption**：能耗监控数据
  - `batteryLevel`：电池电量百分比
  - `charging`：是否正在充电
  - `cpuUsage`：CPU使用率估算
  - `powerLevel`：能耗等级（low/medium/high）
  - `powerScore`：能耗评分（0-100）

## 常见问题

### 1. 内存监控为什么在部分浏览器无效？
- 目前只有 Chrome 支持 `performance.memory`，其他浏览器会自动忽略。

### 2. 如何自定义数据上报？
- 通过 `onData` 回调或配置 `reportUrl`，SDK会自动POST数据到你的接口。

### 3. 如何判断内存泄漏？
- SDK会自动检测内存持续增长趋势，若检测到疑似泄漏会在控制台警告并上报。

### 4. 能耗监控支持哪些设备？
- 支持所有支持Battery API的设备（主要是移动设备），桌面设备会基于内存使用率估算CPU使用率。

## 许可证

MIT