Performance Monitor

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

特性

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

安装

npm install performance-monitor

快速开始

基础使用

import PerformanceMonitor from 'performance-monitor';

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

发送到服务器

// 使用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'
});

自定义输出

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

启用错误监控

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

主要的监控类。

构造函数

new PerformanceMonitor(config?: PerformanceMonitorConfig)

方法

getMetrics(): PerformanceMetrics

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

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

getDetailedMetrics(): Record<string, MetricDetail>

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

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

getErrorCount(): number

获取错误统计数量。

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

reportMetrics(): void

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

monitor.reportMetrics();

disconnect(): void

停止性能监控。

monitor.disconnect();

isReady(): boolean

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

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

updateConfig(newConfig: Partial<PerformanceMonitorConfig>): void

更新配置。

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 (可选)

开发

# 安装依赖
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支持
• 支持多种输出方式
• 添加错误监控功能