擴充功能可以和網頁存取相同的 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 狀態
您可以按照下列步驟,識別服務工作處理程序何時喚醒以執行工作:
- 複製「檢查檢視畫面」上方的擴充功能 ID。
- 在瀏覽器中開啟資訊清單檔案。例如:
text chrome-extension://YOUR_EXTENSION_ID/manifest.json
- 檢查檔案。
- 前往「Application」面板。
- 前往「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"
],
...
}
fetch()
延伸閱讀
如要進一步瞭解 Chrome 開發人員工具,請參閱說明文件。