Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

偵錯欄位效能

瞭解如何使用偵錯資訊歸因成效資料，透過 Analytics 找出並修正實際使用者問題

Philip Walton

Google 提供兩類工具，可評估及偵錯效能：

實驗室工具：例如 Lighthouse，這類工具會在模擬環境中載入網頁，模擬各種情況 (例如網路速度緩慢和低階行動裝置)。
現場工具：例如 Chrome 使用者體驗報告 (CrUX)，這項工具會根據 Chrome 匯總的實際使用者資料，(請注意，PageSpeed Insights 和 Search Console 等工具回報的實際資料，是取自 CrUX 資料。)

雖然現場工具提供的資料更準確 (實際反映真實使用者的體驗)，但實驗室工具通常更適合用來找出及修正問題。

CrUX 資料更能代表網頁的實際成效，但瞭解 CrUX 分數不太可能協助您找出如何提升成效。

另一方面，Lighthouse 會找出問題，並提供具體的改善建議。不過，Lighthouse 只會針對網頁載入時間發現的效能問題提供建議。如果問題只會在使用者互動時發生，例如捲動或點選網頁上的按鈕，這項工具就無法偵測到。

這引出一個重要問題：如何從實際使用者擷取 Core Web Vitals 或其他成效指標的偵錯資訊？

這篇文章將詳細說明可用的 API，協助您收集目前各項 Core Web Vitals 指標的額外偵錯資訊，並提供在現有 Analytics 工具中擷取這項資料的建議。

歸因和偵錯 API

累計版面配置位移 (CLS)

在所有 Core Web Vitals 指標中，或許以CLS 最需要收集現場偵錯資訊。CLS 是在整個網頁生命週期中測量，因此使用者與網頁的互動方式 (捲動距離、點擊內容等)，可能會大幅影響版面配置位移的發生與位移的元素。

請參考以下 PageSpeed Insights 報告：

PageSpeed Insights 報告，顯示不同的 CLS 值 — PageSpeed Insights 會顯示實際和實驗數據 (如有)，兩者可能有所不同

實驗室 (Lighthouse) 報告的 CLS 值與實際 (CrUX 資料) 的 CLS 值差異很大，如果您考量到網頁可能含有大量互動式內容，但 Lighthouse 測試時並未使用這些內容，就會發現這種情況很合理。

但即使您瞭解使用者互動會影響欄位資料，還是需要知道網頁上哪些元素會位移，導致第 75 百分位數的分數為 0.28。LayoutShiftAttribution 介面可協助您達成這個目標。

取得版面配置位移歸因

LayoutShiftAttribution 介面會顯示在 Layout Instability API 發出的每個 layout-shift 項目中。

如需這兩個介面的詳細說明，請參閱「偵錯版面配置位移」。就本文而言，您主要需要瞭解的是，開發人員可以觀察網頁上發生的每次版面配置變化，以及哪些元素發生變化。

以下是程式碼範例，可記錄每次版面配置變動，以及變動的元素：

new PerformanceObserver((list) => {
  for (const {value, startTime, sources} of list.getEntries()) {
    // Log the shift amount and other entry info.
    console.log('Layout shift:', {value, startTime});
    if (sources) {
      for (const {node, curRect, prevRect} of sources) {
        // Log the elements that shifted.
        console.log('  Shift source:', node, {curRect, prevRect});
      }
    }
  }
}).observe({type: 'layout-shift', buffered: true});

測量並將每次發生的版面配置變化資料傳送至分析工具，可能不太實際；不過，監控所有變化後，您就能追蹤最嚴重的變化，並只回報這些變化相關資訊。

我們的目標不是找出並修正每位使用者發生的每個版面配置位移，而是找出影響最多使用者的位移，進而對網頁第 75 百分位 CLS 做出最大貢獻。

此外，您不需要在每次發生位移時都計算最大的來源元素，只要在準備將 CLS 值傳送至分析工具時執行即可。

下列程式碼會取得造成 CLS 的 layout-shift 項目清單，並從最大位移中傳回最大的來源元素：

function getCLSDebugTarget(entries) {
  const largestEntry = entries.reduce((a, b) => {
    return a && a.value > b.value ? a : b;
  });
  if (largestEntry && largestEntry.sources && largestEntry.sources.length) {
    const largestSource = largestEntry.sources.reduce((a, b) => {
      return a.node && a.previousRect.width * a.previousRect.height >
          b.previousRect.width * b.previousRect.height ? a : b;
    });
    if (largestSource) {
      return largestSource.node;
    }
  }
}

找出造成最大變動的最大元素後，即可向數據分析工具回報。

對於特定網頁，造成 CLS 分數最高的元素可能因使用者而異，但如果匯總所有使用者的這些元素，您就能產生一份清單，列出影響最多使用者的位移元素。

找出並修正這些元素位移的根本原因後，您的 Analytics 程式碼就會開始將較小的位移回報為網頁的「最嚴重」位移。最終，所有回報的變化都會夠小，讓網頁遠低於「良好」門檻 0.1！

除了最大位移來源元素，您可能還想擷取以下中繼資料：

最大位移的時間
最大變動時的網址路徑 (適用於動態更新網址的網站，例如單頁應用程式)。

最大內容繪製 (LCP)

如要在實際環境中偵錯 LCP，主要需要瞭解在特定載入網頁期間，哪個元素是最大元素 (LCP 候選元素)。

請注意，即使是完全相同的網頁，不同使用者也可能看到不同的 LCP 候選元素，這其實很常見。

問題的原因如下：

使用者裝置的螢幕解析度各不相同，因此網頁版面配置也會有所差異，導致可視區域內顯示的元素不同。
使用者不一定會載入捲動至最頂端的網頁。連結通常會包含片段 ID，甚至是文字片段，這表示網頁可能會載入並顯示在網頁上的任何捲動位置。
系統可能會為目前使用者提供個人化內容，因此 LCP 候選元素可能因人而異。

也就是說，您無法假設特定網頁最常見的 LCP 候選元素是哪個元素或元素集。您必須根據實際使用者行為進行評估。

找出 LCP 候選元素

如要在 JavaScript 中判斷 LCP 候選元素，可以使用 Largest Contentful Paint API，也就是用來判斷 LCP 時間值的 API。

觀察 largest-contentful-paint 項目時，您可以查看最後一個項目的 element 屬性，判斷目前的 LCP 候選元素：

new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1];

  console.log('LCP element:', lastEntry.element);
}).observe({type: 'largest-contentful-paint', buffered: true});

找出 LCP 候選元素後，即可將該元素連同指標值傳送至分析工具。與 CLS 相同，這項指標可協助您找出最需要優先改善的元素。

除了 LCP 候選元素，測量 LCP 子部分時間也很有幫助，有助於判斷哪些最佳化步驟與網站相關。

Interaction to Next Paint (INP)

在 INP 欄位中，最重要的資訊是：

與哪個元素互動
互動類型
互動發生時間

互動緩慢的主要原因是主執行緒遭到阻斷，而這在載入 JavaScript 時很常見。瞭解大多數緩慢的互動是否發生在網頁載入期間，有助於判斷需要採取哪些行動來修正問題。

INP 指標會考量互動的完整延遲時間，包括執行所有已註冊事件監聽器所需的時間，以及執行所有事件監聽器後，繪製下一個影格所需的時間。也就是說，瞭解哪些目標元素容易導致互動緩慢，以及這些互動的類型，對 INP 來說非常實用。

下列程式碼會記錄 INP 項目目標元素和時間。

function logINPDebugInfo(inpEntry) {
  console.log('INP target element:', inpEntry.target);
  console.log('INP interaction type:', inpEntry.name);
  console.log('INP time:', inpEntry.startTime);
}

請注意，這段程式碼不會顯示如何判斷哪個 event 項目是 INP 項目，因為這項邏輯較為複雜。不過，下一節將說明如何使用 web-vitals JavaScript 程式庫取得這項資訊。

搭配 web-vitals JavaScript 程式庫使用

前幾節提供了一些一般建議和程式碼範例，可擷取偵錯資訊，並納入傳送至分析工具的資料中。

自第 3 版起，web-vitals JavaScript 程式庫包含歸因建構，可顯示所有這類資訊，以及一些額外信號。

下列程式碼範例說明如何設定額外的事件參數 (或自訂維度)，其中包含有助於找出效能問題根本原因的偵錯字串。

import {onCLS, onINP, onLCP} from 'web-vitals/attribution';

function sendToGoogleAnalytics({name, value, id, attribution}) {
  const eventParams = {
    metric_value: value,
    metric_id: id,
  }

  switch (name) {
    case 'CLS':
      eventParams.debug_target = attribution.largestShiftTarget;
      break;
    case 'LCP':
      eventParams.debug_target = attribution.element;
      break;
    case 'INP':
      eventParams.debug_target = attribution.interactionTarget;
      break;
  }

  // Assumes the global `gtag()` function exists, see:
  // https://developers.google.com/analytics/devguides/collection/ga4
  gtag('event', name, eventParams);
}

onCLS(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
onINP(sendToGoogleAnalytics);

這段程式碼專為 Google Analytics 而設，但一般概念也應適用於其他 Analytics 工具。

這段程式碼也只會顯示如何回報單一偵錯信號，但如果能針對每個指標收集及回報多個不同信號，會很有幫助。

舉例來說，如要偵錯 INP，您可能需要收集互動的元素、互動類型、時間、loadState、互動階段等資訊 (例如長動畫影格資料)。

web-vitals 歸因建構版本會顯示額外的歸因資訊，如以下 INP 範例所示：

import {onCLS, onINP, onLCP} from 'web-vitals/attribution';

function sendToGoogleAnalytics({name, value, id, attribution}) {
  const eventParams = {
    metric_value: value,
    metric_id: id,
  }

  switch (name) {
    case 'INP':
      eventParams.debug_target = attribution.interactionTarget;
      eventParams.debug_type = attribution.interactionType;
      eventParams.debug_time = attribution.interactionTime;
      eventParams.debug_load_state = attribution.loadState;
      eventParams.debug_interaction_delay = Math.round(attribution.inputDelay);
      eventParams.debug_processing_duration = Math.round(attribution.processingDuration);
      eventParams.debug_presentation_delay =  Math.round(attribution.presentationDelay);
      break;

    // Additional metric logic...
  }

  // Assumes the global `gtag()` function exists, see:
  // https://developers.google.com/analytics/devguides/collection/ga4
  gtag('event', name, eventParams);
}

onCLS(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
onINP(sendToGoogleAnalytics);

如需完整的偵錯信號清單，請參閱 Web Vitals 歸因說明文件。

製作報表並以圖表呈現資料

開始收集指標值和偵錯資訊後，下一步是匯總所有使用者的資料，開始尋找模式和趨勢。

如先前所述，您不一定需要解決使用者遇到的所有問題，而是要優先處理影響最多使用者的問題，這類問題通常也會對 Core Web Vitals 分數造成最大的負面影響。

如要瞭解如何使用 BigQuery 查詢及視覺化呈現 GA4 資料，請參閱這篇文章。

摘要

希望這篇文章有助於您瞭解如何使用現有的效能 API 和 web-vitals 程式庫取得偵錯資訊，根據實際使用者在現場的造訪情況診斷效能。本指南著重於 Core Web Vitals，但這些概念也適用於偵錯任何可透過 JavaScript 測量的成效指標。

如果您是分析供應商，並希望改善產品及為使用者提供更多偵錯資訊，不妨考慮採用本文所述的部分技術，但請勿僅限於本文提出的想法。這篇文章適用於所有分析工具，但個別分析工具可能 (且應該) 會擷取並回報更多偵錯資訊。

最後，如果您認為 API 本身缺少功能或資訊，導致您無法偵錯這些指標，請將意見回饋傳送至 web-vitals-feedback@googlegroups.com。