useReportWebVitals

useReportWebVitals 鉤子允許您報告核心 Web 指標 (Core Web Vitals)，並可與您的分析服務結合使用。

傳遞給 useReportWebVitals 的新函式會使用當前可用的指標進行呼叫。為避免報告重複數據，請確保回調函式引用不變更（如下方程式碼範例所示）。

pages/_app.js

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

const logWebVitals = (metric) => {
  console.log(metric)
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(logWebVitals)

  return <Component {...pageProps} />
}

作為鉤子參數傳遞的 metric 物件包含以下屬性：

id：當前頁面加載上下文中指標的唯一識別碼
name：效能指標的名稱。可能的值包括特定於 Web 應用程式的 Web 指標名稱（TTFB、FCP、LCP、FID、CLS）
delta：指標當前值與先前值的差異。該值通常以毫秒為單位，表示指標值隨時間的變化
entries：與指標相關聯的效能條目 (Performance Entries) 陣列。這些條目提供有關指標相關效能事件的詳細資訊
navigationType：指示觸發指標收集的導航類型。可能的值包括 "navigate"、"reload"、"back_forward" 和 "prerender"
rating：指標值的定性評級，提供效能評估。可能的值為 "good"、"needs-improvement" 和 "poor"。評級通常是通過將指標值與指示可接受或次優效能的預定義閾值進行比較來確定的
value：效能條目的實際值或持續時間，通常以毫秒為單位。該值提供指標追蹤的效能方面的定量測量。值的來源取決於所測量的特定指標，可以來自各種效能 API (Performance API)

Web 指標

Web 指標 (Web Vitals) 是一組有用的指標，旨在捕捉網頁的用戶體驗。包含以下所有 Web 指標：

您可以使用 name 屬性處理這些指標的所有結果。

pages/_app.js

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

const handleWebVitals = (metric) => {
  switch (metric.name) {
    case 'FCP': {
      // 處理 FCP 結果
    }
    case 'LCP': {
      // 處理 LCP 結果
    }
    // ...
  }
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(handleWebVitals)

  return <Component {...pageProps} />
}

自訂指標

除了上述核心指標外，還有一些額外的自訂指標用於測量頁面水合 (hydrate) 和渲染所需的時間：

Next.js-hydration：頁面開始和完成水合所需的時間（以毫秒為單位）
Next.js-route-change-to-render：路由變更後頁面開始渲染所需的時間（以毫秒為單位）
Next.js-render：路由變更後頁面完成渲染所需的時間（以毫秒為單位）

您可以單獨處理這些指標的所有結果：

pages/_app.js

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

function handleCustomMetrics(metrics) {
  switch (metric.name) {
    case 'Next.js-hydration':
      // 處理水合結果
      break
    case 'Next.js-route-change-to-render':
      // 處理路由變更到渲染的結果
      break
    case 'Next.js-render':
      // 處理渲染結果
      break
    default:
      break
  }
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(handleCustomMetrics)

  return <Component {...pageProps} />
}

這些指標適用於所有支援用戶計時 API (User Timing API) 的瀏覽器。

將結果發送到外部系統

您可以將結果發送到任何端點以測量和追蹤您網站上的真實用戶效能。例如：

function postWebVitals(metrics) {
  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 })
  }
}

useReportWebVitals(postWebVitals)

須知：如果您使用 Google Analytics，使用 id 值可以讓您手動構建指標分佈（以計算百分位數等）

useReportWebVitals(metric => {
  // 如果您像此範例一樣初始化了 Google Analytics，請使用 `window.gtag`：
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics
  window.gtag('event', metric.name, {
    value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value), // 值必須為整數
    event_label: metric.id, // 當前頁面加載的唯一 id
    non_interaction: true, // 避免影響跳出率
  });
}

閱讀更多關於將結果發送到 Google Analytics 的資訊。

useReportWebVitals

useReportWebVitals

Web 指標

自訂指標

將結果發送到外部系統

On this page