useReportWebVitals

useReportWebVitals 钩子允许您上报核心网页指标 (Core Web Vitals)，并可与您的分析服务结合使用。

app/_components/web-vitals.js

'use client'

import { useReportWebVitals } from 'next/web-vitals'

export function WebVitals() {
  useReportWebVitals((metric) => {
    console.log(metric)
  })
}

app/layout.js

import { WebVitals } from './_components/web-vitals'

export default function Layout({ children }) {
  return (
    <html>
      <body>
        <WebVitals />
        {children}
      </body>
    </html>
  )
}

由于 useReportWebVitals 钩子需要 "use client" 指令，最高效的方式是创建一个由根布局导入的独立组件。这样可以将客户端边界严格限制在 WebVitals 组件内。

作为钩子参数传递的 metric 对象包含以下属性：

id: 当前页面加载上下文中指标的唯⼀标识符
name: 性能指标名称。可能值包括特定于网页应用的网页指标名称（TTFB、FCP、LCP、FID、CLS）
delta: 当前指标值与先前值的差值。该值通常以毫秒为单位，表示指标随时间的变化
entries: 与指标关联的性能条目 (Performance Entries) 数组。这些条目提供与指标相关的性能事件的详细信息
navigationType: 指示触发指标收集的导航类型。可能值包括 "navigate"、"reload"、"back_forward" 和 "prerender"
rating: 指标值的定性评级，提供性能评估。可能值为 "good"（良好）、"needs-improvement"（需改进）和 "poor"（较差）。评级通常通过将指标值与预定义阈值进行比较来确定
value: 性能条目的实际值或持续时间（通常以毫秒为单位）。该值提供被跟踪性能方面的定量测量，其来源取决于具体测量的指标，可能来自不同的性能 API

网页指标 (Web Vitals)

网页指标 (Web Vitals) 是一组用于衡量网页用户体验的有用指标，包含以下内容：

首字节时间 (Time to First Byte) (TTFB)
首次内容绘制 (First Contentful Paint) (FCP)
最大内容绘制 (Largest Contentful Paint) (LCP)
首次输入延迟 (First Input Delay) (FID)
累积布局偏移 (Cumulative Layout Shift) (CLS)
下次绘制交互时间 (Interaction to Next Paint) (INP)

您可以使用 name 属性处理所有这些指标的结果。

'use client'

import { useReportWebVitals } from 'next/web-vitals'

export function WebVitals() {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case 'FCP': {
        // 处理 FCP 结果
      }
      case 'LCP': {
        // 处理 LCP 结果
      }
      // ...
    }
  })
}

在 Vercel 上的使用

Vercel 速度分析 (Vercel Speed Insights) 在 Vercel 部署时会自动配置，无需使用 useReportWebVitals。此钩子在本地开发或使用其他分析服务时非常有用。

将结果发送至外部系统

您可以将结果发送至任何端点以测量和跟踪站点的真实用户性能。例如：

useReportWebVitals((metric) => {
  const body = JSON.stringify(metric)
  const url = 'https://example.com/analytics'

  // 优先使用 `navigator.sendBeacon()`，回退到 `fetch()`
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
})

须知：如果您使用 Google Analytics，利用 id 值可以手动构建指标分布（用于计算百分位数等）

useReportWebVitals(metric => {
  // 使用 `window.gtag` 如果您按照此示例初始化了 Google Analytics：
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_app.js
  window.gtag('event', metric.name, {
    value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value), // 值必须为整数
    event_label: metric.id, // 当前页面加载的唯一标识
    non_interaction: true, // 避免影响跳出率
  });
}

了解更多关于发送结果至 Google Analytics 的信息。

useReportWebVitals

useReportWebVitals

网页指标 (Web Vitals)

在 Vercel 上的使用

将结果发送至外部系统

On this page