useReportWebVitals

useReportWebVitals 鉤子 (hook) 讓您能回報 核心網頁指標 (Core Web Vitals)，並可與您的分析服務搭配使用。

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

function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    console.log(metric)
  })

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

useReportWebVitals

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

• id：當前頁面載入情境下該指標的唯一識別碼
• name：效能指標的名稱。可能的值包括特定於網頁應用的 網頁指標 (Web Vitals) 名稱（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 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 屬性來處理這些指標的所有結果。

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

function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case 'FCP': {
        // 處理 FCP 結果
      }
      case 'LCP': {
        // 處理 LCP 結果
      }
      // ...
    }
  })

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

自訂指標

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

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

您可以分別處理這些指標的結果：

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

function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case 'Next.js-hydration':
        // 處理水合結果
        break
      case 'Next.js-route-change-to-render':
        // 處理路由變更至渲染的結果
        break
      case 'Next.js-render':
        // 處理渲染結果
        break
      default:
        break
    }
  })

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

這些指標在所有支援 使用者計時 API (User Timing API) 的瀏覽器中均可使用。

在 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 => {
  // 如果您像此範例初始化了 Google Analytics，請使用 `window.gtag`：
  // 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 的資訊。