useReportWebVitals

useReportWebVitals 鉤子 (hook) 讓您能回報核心網頁指標 (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" 指令，最有效率的做法是建立一個獨立的元件，並由根佈局 (root layout) 導入。這樣可以將客戶端邊界 (client boundary) 限制在 WebVitals 元件內。

作為鉤子參數傳入的 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 屬性來處理這些指標的所有結果。

'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 => {
  // 如果您像此範例初始化了 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 的資訊。

useReportWebVitals

useReportWebVitals

網頁指標 (Web Vitals)

在 Vercel 上的使用

將結果發送到外部系統

On this page