偵錯擴充功能

擴充功能可以和網頁存取相同的 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"],
  ...
}

請儲存擴充功能，然後再次嘗試載入。這次應該可以成功載入。在擴充功能中 「管理」頁面會顯示三個按鈕：「詳細資料」、「移除」和「錯誤」。錯誤 發生錯誤時，按鈕標籤會變成紅色。按一下「Errors」按鈕即可查看 下列錯誤：

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

接著變更權限，請先變更權限，再按一下右上角的「全部清除」清除記錄，並重新載入擴充功能。

，瞭解如何調查及移除這項存取權。

對 Service Worker 進行偵錯

找出記錄檔

Service Worker 會將預設顏色設為儲存空間，並記錄在控制台中。如要查看此記錄，請選取「Inspect view」旁的藍色連結，開啟 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

如要透過內容指令碼使用開發人員工具，請按一下「top」旁邊的下拉式箭頭，然後選取擴充功能。

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

監控網路要求

彈出式視窗通常會先發出所有必要的網路要求， 開發人員可以開啟開發人員工具如要查看這些要求，請在網路面板中重新整理。這項服務 重新載入彈出式視窗，且不關閉開發人員工具面板。

宣告權限

部分擴充功能 API 需要相關權限請參閱權限一文和 Chrome API，確保擴充功能在資訊清單中要求正確的權限。

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

延伸閱讀

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