# npm
npm install web-vitals
 
# yarn
yarn add web-vitals
 
# pnpm
pnpm add web-vitals
 
# CDN
<script type="module">
  import { onLCP, onINP, onCLS } from 'https://unpkg.com/web-vitals@5/dist/web-vitals.es.js';
</script>

// 导入所需指标的测量函数
import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals';
 
// 注册回调函数，当指标可用时触发
onCLS(sendToAnalytics);
onINP(sendToAnalytics);
onLCP(sendToAnalytics);
onFCP(sendToAnalytics);
onTTFB(sendToAnalytics);
 
// 发送数据到你的分析服务
function sendToAnalytics(metric) {
  // metric 对象包含：
  // - name: 指标名称（如 'CLS', 'INP', 'LCP'）
  // - value: 指标值
  // - rating: 'good' | 'needs-improvement' | 'poor'
  // - delta: 与上次值的差异
  // - id: 页面生命周期 ID
  // - navigationType: 'navigate' | 'reload' | 'back-forward' 等
  // - entries: 底层 PerformanceEntry 数组
 
  const body = JSON.stringify({
    name: metric.name,
    value: metric.value,
    rating: metric.rating,
    delta: metric.delta,
    id: metric.id,
    navigationType: metric.navigationType,
    url: window.location.href,
  });
 
  // 使用 sendBeacon 确保数据在页面卸载时也能发送
  if (navigator.sendBeacon) {
    navigator.sendBeacon('/analytics', body);
  }
}

import { onLCP, onINP, onCLS } from 'web-vitals';
 
// 最简单的用法：将 Core Web Vitals 发送到控制台
onLCP(console.log);
onINP(console.log);
onCLS(console.log);

import { onLCP, onINP, onCLS } from 'web-vitals';
 
// reportAllChanges: true 会在指标值每次变化时触发回调（而不仅是最终值）
onLCP(console.log, { reportAllChanges: true });
onINP(console.log, { reportAllChanges: true });
onCLS(console.log, { reportAllChanges: true });

// Attribution 构建包含额外的诊断信息
import { onLCP, onINP, onCLS } from 'web-vitals/attribution';
 
onLCP((metric) => {
  console.log('LCP:', metric.value);
  console.log('LCP Element:', metric.attribution.element);
  console.log('LCP URL:', metric.attribution.url);
  console.log('LCP Time to First Byte:', metric.attribution.timeToFirstByte);
  console.log('LCP Resource Load Delay:', metric.attribution.resourceLoadDelay);
  console.log('LCP Resource Load Time:', metric.attribution.resourceLoadTime);
  console.log('LCP Element Render Delay:', metric.attribution.elementRenderDelay);
});
 
onINP((metric) => {
  console.log('INP:', metric.value);
  console.log('Event Type:', metric.attribution.eventType);
  console.log('Interaction Target:', metric.attribution.interactionTarget);
  console.log('Interaction Target Selector:', metric.attribution.interactionTargetSelector);
  console.log('Interaction Time:', metric.attribution.interactionTime);
  console.log('Input Delay:', metric.attribution.inputDelay);
  console.log('Processing Duration:', metric.attribution.processingDuration);
  console.log('Presentation Delay:', metric.attribution.presentationDelay);
});
 
onCLS((metric) => {
  console.log('CLS:', metric.value);
  console.log('Largest Shift Target:', metric.attribution.largestShiftTarget);
  console.log('Largest Shift Selector:', metric.attribution.largestShiftSelector);
  console.log('Largest Shift Value:', metric.attribution.largestShiftValue);
  console.log('Largest Shift Time:', metric.attribution.largestShiftTime);
});

interface Metric {
  // 基本信息
  name: 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB';
  value: number;                    // 指标值
  delta: number;                    // 与上次报告的变化量
  id: string;                       // 页面生命周期唯一 ID
  rating: 'good' | 'needs-improvement' | 'poor';
 
  // 导航信息
  navigationType: 'navigate' | 'reload' | 'back-forward' |
                  'back-forward-cache' | 'prerender';
 
  // 底层数据
  entries: PerformanceEntry[];       // 底层 Performance API 条目
 
  // Attribution（仅 attribution 构建）
  attribution?: Attribution;
}

import { useEffect } from 'react';
import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals';
 
export function useWebVitals() {
  useEffect(() => {
    const metrics = {
      onCLS, onINP, onLCP, onFCP, onTTFB,
    };
 
    Object.entries(metrics).forEach(([name, fn]) => {
      fn((metric) => {
        // 发送到你的分析服务
        console.log(`${name}:`, metric);
        sendToAnalytics(metric);
      });
    });
  }, []);
}
 
function sendToAnalytics(metric: Metric) {
  // 使用 Google Analytics
  if (typeof window !== 'undefined' && window.gtag) {
    const body = {
      name: metric.name,
      value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value),
      event_category: 'Web Vitals',
      non_interaction: true,
    };
    window.gtag('event', metric.name, body);
  }
}

import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals';
 
function sendToGoogleAnalytics({ name, delta, value, id }) {
  // 使用 GA4 的 gtag.js
  gtag('event', name, {
    // metric_value 应四舍五入到整数（CLS 乘以 1000）
    value: Math.round(name === 'CLS' ? delta * 1000 : delta),
    metric_id: id,
    metric_value: value,
    metric_delta: Math.round(name === 'CLS' ? delta * 1000 : delta),
    non_interaction: true,  // 避免影响跳出率
  });
}
 
onCLS(sendToGoogleAnalytics);
onINP(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
onFCP(sendToGoogleAnalytics);
onTTFB(sendToGoogleAnalytics);

// app/layout.tsx (Next.js App Router)
import { WebVitals } from './web-vitals';
 
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <WebVitals />
      </body>
    </html>
  );
}
 
// app/web-vitals.tsx
'use client';
 
import { useReportWebVitals } from 'next/web-vitals';
 
export function WebVitals() {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case 'CLS':
        console.log('CLS:', metric.value);
        break;
      case 'INP':
        console.log('INP:', metric.value);
        break;
      case 'LCP':
        console.log('LCP:', metric.value);
        break;
      case 'FCP':
        console.log('FCP:', metric.value);
        break;
      case 'TTFB':
        console.log('TTFB:', metric.value);
        break;
    }
  });
 
  return null;
}

import * as Sentry from '@sentry/browser';
import { onCLS, onINP, onLCP } from 'web-vitals';
 
onCLS((metric) => {
  Sentry.metrics.distribution('web-vitals.cls', metric.value, {
    unit: 'none',
    tags: {
      rating: metric.rating,
    },
  });
});
 
onINP((metric) => {
  Sentry.metrics.distribution('web-vitals.inp', metric.value, {
    unit: 'millisecond',
    tags: {
      rating: metric.rating,
    },
  });
});
 
onLCP((metric) => {
  Sentry.metrics.distribution('web-vitals.lcp', metric.value, {
    unit: 'millisecond',
    tags: {
      rating: metric.rating,
    },
  });
});

import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals';
import { onLCP as onLCPAttr, onINP as onINPAttr, onCLS as onCLSAttr } from 'web-vitals/attribution';
 
// 生成页面唯一 ID
const pageId = generatePageId();
 
function generatePageId() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
    const r = (Math.random() * 16) | 0;
    const v = c === 'x' ? r : (r & 0x3) | 0x8;
    return v.toString(16);
  });
}
 
// 批量发送指标
let pendingMetrics = [];
let sendTimer = null;
 
function queueMetric(metric) {
  pendingMetrics.push({
    pageId,
    name: metric.name,
    value: metric.name === 'CLS' ? Math.round(metric.value * 1000) : Math.round(metric.value),
    rating: metric.rating,
    delta: metric.name === 'CLS' ? Math.round(metric.delta * 1000) : Math.round(metric.delta),
    id: metric.id,
    navigationType: metric.navigationType,
    url: window.location.href,
    timestamp: Date.now(),
    // Attribution 数据（如果有）
    attribution: metric.attribution || null,
  });
 
  // 防抖发送（每 5 秒或页面卸载时）
  clearTimeout(sendTimer);
  sendTimer = setTimeout(flushMetrics, 5000);
}
 
function flushMetrics() {
  if (pendingMetrics.length === 0) return;
 
  const body = JSON.stringify({ metrics: pendingMetrics });
 
  if (navigator.sendBeacon) {
    navigator.sendBeacon('/api/vitals', body);
  } else {
    fetch('/api/vitals', {
      method: 'POST',
      body,
      keepalive: true,
      headers: { 'Content-Type': 'application/json' },
    });
  }
 
  pendingMetrics = [];
}
 
// 页面卸载时立即发送
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    flushMetrics();
  }
});
 
// 注册所有指标（标准构建）
onCLS(queueMetric);
onINP(queueMetric);
onLCP(queueMetric);
onFCP(queueMetric);
onTTFB(queueMetric);
 
// 如果需要诊断信息，使用 attribution 构建
// onCLSAttr(queueMetric);
// onINPAttr(queueMetric);
// onLCPAttr(queueMetric);