偵錯擴充功能

擴充功能可以存取網頁中的 Chrome 開發人員工具。您必須瞭解如何找出不同擴充功能元件的記錄和錯誤，才能成為偵錯擴充功能的專家。本教學課程提供對擴充功能偵錯的基本技巧。

事前準備

本指南假設您具備基本的網頁開發經驗。建議您參閱「開發基本概念」，進一步瞭解擴充功能開發工作流程。設計使用者介面：說明擴充功能中可用的使用者介面元素。

中斷擴充功能

本教學課程將一次中斷一個擴充功能元件，並示範如何修正。請記得復原在某一部分導入的錯誤，再繼續進行下一節。首先，從 GitHub 下載 Broken Color 範例。

對資訊清單進行偵錯

首先，請將 "version" 鍵變更為 "versions"，藉此分割資訊清單檔案：

manifest.json:

{
  "name": "Broken Background Color",
  "version": "1.0",
  "versions": "1.0",
  "description": "Fix an Extension!",
  ...
}

現在，讓我們試著在本機載入擴充功能。您會看到一個錯誤對話方塊，指出您的問題：

Failed to load extension
Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536.
Could not load manifest.

如果資訊清單金鑰無效，擴充功能就無法載入，但 Chrome 會提示修正問題。

復原變更，然後輸入無效權限，看看會發生什麼情況。 將 "activeTab" 權限變更為小寫 "activetab"：

manifest.json:

{
  ...
  "permissions": ["activeTab", "scripting", "storage"],
  "permissions": ["activetab", "scripting", "storage"],
  ...
}

儲存擴充功能並嘗試重新載入。這次應該可以順利載入。擴充功能管理頁面會顯示三個按鈕：「Details」(詳細資料)、「Remove」(移除) 和「Errors」(錯誤)。發生錯誤時，「Errors」按鈕標籤會變成紅色。點選「Errors」按鈕即可查看下列錯誤：

Permission 'activetab' is unknown or URL pattern is malformed.

如要繼續，請先變更權限，然後按一下右上角的「全部清除」清除記錄，然後重新載入擴充功能。

對 Service Worker 進行偵錯

找出記錄檔

Service Worker 會將預設顏色設為儲存空間，並記錄至控制台。如要查看這項記錄，請選取「檢查檢視畫面」旁的藍色連結，開啟 Chrome 開發人員工具面板。

找出錯誤

讓我們將 onInstalled 變更為小寫 oninstalled，藉此中斷 Service Worker：

service-worker.js：

// There's a typo in the line below;
// ❌ oninstalled should be ✅ onInstalled.
chrome.runtime.onInstalled.addListener(() => { 
chrome.runtime.oninstalled.addListener(() => { 
  chrome.storage.sync.set({ color: '#3aa757' }, () => {
    console.log('The background color is green.');
  });
});

重新整理並按一下「錯誤」，即可查看錯誤記錄。第一個錯誤會通知您 Service Worker 無法註冊。這表示啟動時發生錯誤：

Service worker registration failed. Status code: 15.

以下實際錯誤發生之後：

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')

如要復原導入的錯誤，請按一下右上角的「全部清除」，然後重新載入擴充功能。

檢查 Service Worker 狀態

您可以按照下列步驟，找出服務工作站何時醒來以便執行工作：

1. 複製「檢查檢視畫面」上方的擴充功能 ID。

   

2. 在瀏覽器中開啟資訊清單檔案。例如： text chrome-extension://YOUR_EXTENSION_ID/manifest.json
3. 檢查檔案。
4. 前往「Application」面板。
5. 前往「Service Workers」窗格。

如要測試程式碼，請使用「狀態」旁的連結來啟動或停止 Service Worker。

此外，如果您變更了 Service Worker 程式碼，可以按一下「Update」或「skipWaiting」立即套用變更。

對彈出式視窗進行偵錯

現在擴充功能已正確初始化，讓我們透過註解下方醒目顯示的程式碼來破壞彈出式視窗：

popup.js:

...
changeColorButton.addEventListener('click', (event) => {
  const color = event.target.value;

  // Query the active tab before injecting the content script
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => { 
    // Use the Scripting API to execute a script
    chrome.scripting.executeScript({
      target: { tabId: tabs[0].id },
      args: [color],
      func: setColor
    });
  });
});

返回「擴充功能管理」頁面。「Errors」按鈕會重新顯示。按一下即可檢視新的記錄。系統會顯示下列錯誤訊息：

Uncaught ReferenceError: tabs is not defined

只要檢查彈出式視窗，即可開啟彈出式視窗的開發人員工具。

錯誤訊息 tabs is undefined 表示擴充功能不知道插入內容指令碼的位置。如要修正這個問題，請呼叫 tabs.query()，然後選取使用中的分頁。

如要更新程式碼，請按一下右上角的「全部清除」按鈕，然後重新載入擴充功能。

偵錯內容指令碼

現在，讓我們將變數「color」變更為「colors」，以破壞內容指令碼。

content.js:

...
function setColor(color) {
  // There's a typo in the line below;
  // ❌ colors should be ✅ color.
  document.body.style.backgroundColor = color;
  document.body.style.backgroundColor = colors;
}  

重新整理頁面、開啟彈出式視窗，然後按一下綠色方塊。但這個按鈕沒有任何作用。

如果您前往「擴充功能管理」頁面，畫面上不會顯示「錯誤」按鈕。這是因為「擴充功能管理」頁面只會記錄執行階段錯誤 console.warning 和 console.error。

內容指令碼會在網站內執行，因此，如要找出這些錯誤，我們必須檢查擴充功能試圖變更的網頁：

Uncaught ReferenceError: colors is not defined

如要在內容指令碼中使用開發人員工具，請按一下頂端旁的下拉式箭頭並選取擴充功能。

錯誤訊息顯示「colors」未定義。擴充功能不得正確傳遞變數。修正插入的指令碼，將顏色變數傳入程式碼中。

監控網路要求

彈出式視窗通常會發出所有必要的網路要求，直到開發人員快開啟開發人員工具為止。如要查看這些要求，請在網路面板中重新整理。系統隨即重新載入彈出式視窗，但不會關閉開發人員工具面板。

宣告權限

某些擴充功能 API 需要權限。請參閱權限一文和 Chrome API，確認擴充功能正在要求資訊清單中的適當權限。

  {
    "name": "Broken Background Color",
    ...
    "permissions": [
      "activeTab",
      "declarativeContent",
      "storage"
    ],
  ...
  }

其他資訊

如要進一步瞭解 Chrome 開發人員工具，請參閱說明文件。