偵錯擴充功能

擴充功能可以和網頁存取相同的 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 開發人員工具面板。

開啟擴充功能 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.
敬上
Service Worker 註冊失敗。狀態碼:15 則錯誤訊息
Service Worker 註冊錯誤訊息。
,瞭解如何調查及移除這項存取權。

實際錯誤發生在:

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')
敬上
Uncaught TypeError:無法讀取未定義錯誤訊息的屬性
未擷取的 TypeError 訊息。

請復原我們介紹的錯誤,請按一下右上角的「全部清除」,然後重新載入擴充功能。

查看 Service Worker 狀態

您可以按照下列步驟,識別服務工作處理程序何時喚醒以執行工作:

  1. 複製「檢查檢視畫面」上方的擴充功能 ID。
    「擴充功能管理」頁面中的擴充功能 ID
    「擴充功能管理」頁面中的擴充功能 ID。
  2. 在瀏覽器中開啟資訊清單檔案。例如: text chrome-extension://YOUR_EXTENSION_ID/manifest.json
  3. 檢查檔案。
  4. 前往「Application」面板。
  5. 前往「Service Workers」窗格。

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

「應用程式」面板中的服務工作站狀態
「Applications」面板中的 Service Worker 狀態。(按一下可放大圖片)。

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

「應用程式」面板中的服務工作站狀態
在「應用程式」面板中重新整理 Service Worker。(按一下可放大圖片)。
,瞭解如何調查及移除這項存取權。

對彈出式視窗進行偵錯

現在擴充功能已正確初始化,讓我們為下方醒目顯示的行加上註解,以中斷彈出式視窗:

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」旁邊的下拉式箭頭,然後選取擴充功能。

未偵測到的參考錯誤:未定義顏色
Uncaught ReferenceError:未定義顏色。

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

監控網路要求

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

在網路面板中重新整理,即可查看彈出式聯播網要求
在網路面板中重新整理,即可查看彈出式網路要求。

宣告權限

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

  {
    "name": "Broken Background Color",
    ...
    "permissions": [
      "activeTab",
      "declarativeContent",
      "storage"
    ],
  ...
  }
敬上 fetch()

延伸閱讀

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