fps-auto-report

v1.3.0

Published

22 days ago

A npm package for FPS monitoring and performance reporting with web-vitals integration

0High
0Medium
0Low

chenzuge

fps performance monitoring web-vitals reporting

fps-auto-report

一个用于监控帧率（FPS）和性能指标并自动上报的 npm 包，集成了 Google 官方的 web-vitals 库。

功能特性

✅ FPS 统计：实时监控页面帧率，提供平均、最小、最大 FPS 数据
✅ Web Vitals 集成：自动收集 CLS、FCP、LCP、TTFB、INP 等性能指标（基于 web-vitals 5.x）
✅ 混合上报策略：FPS 和 Web Vitals 独立上报，互不耦合
- FPS：支持基于卡顿等级的智能上报或固定间隔上报
- Web Vitals：支持事件驱动上报（指标变化时）或固定间隔上报
✅ 页面信息收集：自动收集 URL、标题、视口大小等页面信息，支持自定义扩展
✅ 可配置上报：支持自定义上报接口和上报方式，避免内置上传接口
✅ 灵活使用：可作为第三方包在不同项目中使用
✅ TypeScript 支持：完整的 TypeScript 类型定义

安装

npm install fps-auto-report web-vitals

或

yarn add fps-auto-report web-vitals

或

pnpm add fps-auto-report web-vitals

使用方法

基础用法

import { createFPSReporter } from 'fps-auto-report';

// 创建上报器实例
const reporter = createFPSReporter({
  reportUrl: 'https://your-api.com/report',
  reportMethod: 'POST'
});

// 开始监控和上报
reporter.start();

完整配置示例

import { createFPSReporter } from 'fps-auto-report';

const reporter = createFPSReporter({
  // 必填：上报接口地址（如果使用自定义上报函数则可不填）
  reportUrl: 'https://your-api.com/report',
  
  // 可选：上报方法，默认 POST
  reportMethod: 'POST', // 'POST' | 'GET' | 'PUT' | 'PATCH'
  
  // 可选：自定义上报函数（优先级高于 reportUrl）
  customReporter: async (data) => {
    // 自定义上报逻辑
    await fetch('https://your-api.com/custom-report', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
  },
  
  // 可选：FPS 统计间隔（毫秒），默认 1000
  fpsInterval: 1000,
  
  // 可选：是否启用 web-vitals 统计，默认 true
  enableWebVitals: true,
  
  // 可选：是否自动上报，默认 true
  autoReport: true,
  
  // 可选：上报间隔（毫秒），默认 5000
  reportInterval: 5000,
  
  // 可选：是否在页面卸载时上报，默认 true
  reportOnUnload: true,
  
  // 可选：自定义页面信息收集函数
  collectPageInfo: () => {
    return {
      url: window.location.href,
      title: document.title,
      customField: 'custom value',
      // 可以添加任意自定义字段
    };
  },
  
  // 可选：请求头配置
  headers: {
    'Authorization': 'Bearer token',
    'X-Custom-Header': 'value'
  },
  
  // 可选：是否启用调试模式，默认 false
  debug: true,
  
  // ========== 混合上报策略配置（推荐） ==========
  
  // FPS 上报策略
  fpsReportStrategy: {
    enabled: true,              // 是否启用 FPS 上报，默认 true
    levelBased: true,           // 是否启用基于等级的智能上报，默认 true
    interval: 5000,             // 固定上报间隔（当 levelBased 为 false 时使用）
    levelThresholds: {          // FPS 等级阈值
      excellent: 55,
      good: 45,
      fair: 30,
      poor: 20
    },
    levelStrategy: {            // 各等级上报间隔（毫秒）
      excellent: 30000,         // 优秀：30秒
      good: 5000,               // 良好：5秒
      fair: 5000,               // 一般：5秒
      poor: 2000,               // 较差：2秒
      severe: 1000              // 严重：1秒
    }
  },
  
  // Web Vitals 上报策略
  webVitalsReportStrategy: {
    enabled: true,              // 是否启用 Web Vitals 上报，默认 true
    reportOnChange: true,       // 指标变化时立即上报（推荐），默认 true
    reportOnFirst: true,        // 指标首次出现时上报，默认 true
    reportInterval: 5000       // 固定上报间隔（当 reportOnChange 为 false 时使用）
  }
});

// 开始监控
reporter.start();

混合上报策略示例

import { createFPSReporter } from 'fps-auto-report';

const reporter = createFPSReporter({
  reportUrl: 'https://your-api.com/report',
  
  // FPS 按等级智能上报
  fpsReportStrategy: {
    enabled: true,
    levelBased: true,
    levelThresholds: { excellent: 55, good: 45, fair: 30, poor: 20 },
    levelStrategy: {
      excellent: 30000,  // 优秀时降低上报频率
      good: 5000,
      fair: 5000,
      poor: 2000,        // 较差时提高上报频率
      severe: 1000       // 严重时高频上报
    }
  },
  
  // Web Vitals 事件驱动上报
  webVitalsReportStrategy: {
    enabled: true,
    reportOnChange: true,   // 指标变化时立即上报
    reportOnFirst: true     // 首次出现时上报
  }
});

reporter.start();

手动上报

// 上报所有数据（FPS + Web Vitals）
await reporter.report();
// 或
await reporter.reportAll();

// 仅上报 FPS 数据
await reporter.reportFPS();

// 仅上报 Web Vitals 数据
await reporter.reportWebVitals();

// 获取当前 FPS 数据
const fpsData = reporter.getFPSData();
console.log('Current FPS:', fpsData.fps);
console.log('FPS Level:', fpsData.level);
console.log('Average FPS:', fpsData.averageFPS);

// 获取 web-vitals 指标
const metrics = reporter.getWebVitalsMetrics();
console.log('Web Vitals:', metrics);

// 重置统计数据
reporter.reset();

// 停止监控
reporter.stop();

使用类方式

import FPSReporter from 'fps-auto-report';

const reporter = new FPSReporter({
  reportUrl: 'https://your-api.com/report'
});

reporter.start();

配置选项

FPSReporterConfig

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | reportUrl | string | 否* | - | 上报接口地址（如果使用 customReporter 则可不填） | | reportMethod | 'POST' \| 'GET' \| 'PUT' \| 'PATCH' | 否 | 'POST' | 上报方法 | | customReporter | (data: ReportData) => void \| Promise<void> | 否 | - | 自定义上报函数 | | fpsInterval | number | 否 | 1000 | FPS 统计间隔（毫秒） | | enableWebVitals | boolean | 否 | true | 是否启用 web-vitals 统计 | | autoReport | boolean | 否 | true | 是否自动上报 | | reportInterval | number | 否 | 5000 | 上报间隔（毫秒） | | reportOnUnload | boolean | 否 | true | 是否在页面卸载时上报 | | collectPageInfo | () => PageInfo \| Promise<PageInfo> | 否 | 默认收集函数 | 自定义页面信息收集函数 | | headers | Record<string, string> | 否 | {} | 请求头配置 | | debug | boolean | 否 | false | 是否启用调试模式 | | fpsReportStrategy | FPSReportStrategy | 否 | 见下方 | FPS 上报策略配置 | | webVitalsReportStrategy | WebVitalsReportStrategy | 否 | 见下方 | Web Vitals 上报策略配置 |

FPSReportStrategy

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用 FPS 上报 | | levelBased | boolean | true | 是否启用基于等级的智能上报 | | interval | number | 5000 | 固定上报间隔（毫秒，当 levelBased 为 false 时使用） | | levelThresholds | FPSLevelThresholds | 见下方 | FPS 等级阈值配置 | | levelStrategy | FPSLevelReportStrategy | 见下方 | FPS 等级上报策略配置 |

WebVitalsReportStrategy

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用 Web Vitals 上报 | | reportOnChange | boolean | true | 指标变化时立即上报（推荐） | | reportOnFirst | boolean | true | 指标首次出现时上报 | | reportInterval | number | 5000 | 固定上报间隔（毫秒，当 reportOnChange 为 false 时使用） |

数据类型

ReportData

上报的数据结构：

interface ReportData {
  fps?: FPSData;           // FPS 统计数据
  webVitals?: Metric[];    // web-vitals 指标数组
  pageInfo: PageInfo;      // 页面信息
  timestamp: number;        // 时间戳
}

FPSData

FPS 统计数据：

interface FPSData {
  fps: number;             // 当前 FPS
  averageFPS: number;       // 平均 FPS
  minFPS: number;          // 最小 FPS
  maxFPS: number;          // 最大 FPS
  frameCount: number;       // 帧数
  timestamp: number;        // 时间戳
}

PageInfo

页面信息（可扩展）：

interface PageInfo {
  url: string;             // 页面 URL
  title?: string;          // 页面标题
  referrer?: string;       // 来源页面
  userAgent?: string;      // 用户代理
  viewport?: {             // 视口大小
    width: number;
    height: number;
  };
  timestamp?: number;       // 时间戳
  [key: string]: any;      // 自定义字段
}

上报策略说明

混合策略设计

本库采用混合上报策略，FPS 和 Web Vitals 独立上报，互不耦合：

FPS 上报：
- 基于卡顿等级的智能上报（推荐）：根据 FPS 值自动划分等级，不同等级采用不同上报频率
- 固定间隔上报：按固定时间间隔上报
Web Vitals 上报：
- 事件驱动上报（推荐）：指标变化或首次出现时立即上报，符合 Web Vitals 的特性
- 固定间隔上报：按固定时间间隔上报

为什么需要混合策略？

FPS 是持续变化的实时指标，适合按等级动态调整上报频率
Web Vitals 指标通常在特定时机出现（如页面加载、用户交互），适合事件驱动上报
两者独立上报，避免相互影响，更符合各自的数据特性

注意事项

依赖要求：需要安装 web-vitals 作为 peer dependency
浏览器兼容性：需要支持 requestAnimationFrame 和 performance.now() 的现代浏览器
上报接口：确保你的上报接口能够处理 JSON 格式的数据
页面卸载上报：使用 sendBeacon API 确保页面卸载时数据能够可靠上报
向后兼容：旧版配置（enableLevelBasedReport、fpsLevelThresholds 等）仍然支持，但推荐使用新的策略配置

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（监听文件变化）
npm run dev

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

fps-auto-report

功能特性

安装

使用方法

基础用法

完整配置示例

混合上报策略示例

手动上报

使用类方式

配置选项

FPSReporterConfig

FPSReportStrategy

WebVitalsReportStrategy

数据类型

ReportData

FPSData

PageInfo

上报策略说明

混合策略设计

为什么需要混合策略？

注意事项

开发

License