擴充功能可以存取網頁中的 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.
![資訊清單索引鍵無效擴充功能,在嘗試載入時觸發錯誤對話方塊。](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/an-extension-an-invalid-9ab91f867f94c.png?authuser=3&hl=zh-tw)
如果資訊清單金鑰無效,擴充功能就無法載入,但 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.
![點選錯誤按鈕並顯示錯誤](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/error-button-is-clicked-a7713a11553a.gif?authuser=3&hl=zh-tw)
如要繼續,請先變更權限,然後按一下右上角的「全部清除」清除記錄,然後重新載入擴充功能。
![「全部清除」按鈕](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/clear-button-2f67dd9230519.png?authuser=3&hl=zh-tw)
對 Service Worker 進行偵錯
找出記錄檔
Service Worker 會將預設顏色設為儲存空間,並記錄至控制台。如要查看這項記錄,請選取「檢查檢視畫面」旁的藍色連結,開啟 Chrome 開發人員工具面板。
![開啟擴充功能 Service Worker 的開發人員工具。](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/opening-devtools-the-ex-685e204e20773.png?authuser=3&hl=zh-tw)
找出錯誤
讓我們將 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 則錯誤訊息](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/service-worker-registrati-9791df79120e6.png?authuser=3&hl=zh-tw)
以下實際錯誤發生之後:
Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')
![Uncaught TypeError:無法讀取未定義錯誤訊息的屬性](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/uncaught-typeerror-canno-45ae014961338.png?authuser=3&hl=zh-tw)
如要復原導入的錯誤,請按一下右上角的「全部清除」,然後重新載入擴充功能。
檢查 Service Worker 狀態
您可以按照下列步驟,找出服務工作站何時醒來以便執行工作:
- 複製「檢查檢視畫面」上方的擴充功能 ID。
「擴充功能管理」頁面中的擴充功能 ID。 - 在瀏覽器中開啟資訊清單檔案。例如:
text chrome-extension://YOUR_EXTENSION_ID/manifest.json
- 檢查檔案。
- 前往「Application」面板。
- 前往「Service Workers」窗格。
如要測試程式碼,請使用「狀態」旁的連結來啟動或停止 Service Worker。
![「應用程式」面板中的 Service Worker 狀態](https://developer.chrome.google.cn/docs/extensions/get-started/tutorial/debug/image/start-stop-service-worker.png?auto=format&w=845&authuser=3&hl=zh-tw)
此外,如果您變更了 Service Worker 程式碼,可以按一下「Update」或「skipWaiting」立即套用變更。
![「應用程式」面板中的 Service Worker 狀態](https://developer.chrome.google.cn/docs/extensions/get-started/tutorial/debug/image/update-or-skipwaiting.png?auto=format&w=845&authuser=3&hl=zh-tw)
對彈出式視窗進行偵錯
現在擴充功能已正確初始化,讓我們透過註解下方醒目顯示的程式碼來破壞彈出式視窗:
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
![「擴充功能管理」頁面顯示彈出式錯誤](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/extensions-management-pag-00a0f48a76239.png?authuser=3&hl=zh-tw)
只要檢查彈出式視窗,即可開啟彈出式視窗的開發人員工具。
![開發人員工具顯示彈出式視窗錯誤。](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/devtools-displaying-popup-0ed24fd80361a.png?authuser=3&hl=zh-tw)
錯誤訊息 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
![網頁控制台顯示擴充功能錯誤](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/extension-error-displayed-ca9d8c6c336b.png?authuser=3&hl=zh-tw)
如要在內容指令碼中使用開發人員工具,請按一下頂端旁的下拉式箭頭並選取擴充功能。
![未偵測到的 ReferenceError:未定義顏色](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/uncaught-referenceerror-e5847be3a7de9.png?authuser=3&hl=zh-tw)
錯誤訊息顯示「colors
」未定義。擴充功能不得正確傳遞變數。修正插入的指令碼,將顏色變數傳入程式碼中。
監控網路要求
彈出式視窗通常會發出所有必要的網路要求,直到開發人員快開啟開發人員工具為止。如要查看這些要求,請在網路面板中重新整理。系統隨即重新載入彈出式視窗,但不會關閉開發人員工具面板。
![重新整理網路面板即可查看彈出式網路要求](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/refresh-inside-network-p-43993068e650e.gif?authuser=3&hl=zh-tw)
宣告權限
某些擴充功能 API 需要權限。請參閱權限一文和 Chrome API,確認擴充功能正在要求資訊清單中的適當權限。
{
"name": "Broken Background Color",
...
"permissions": [
"activeTab",
"declarativeContent",
"storage"
],
...
}
其他資訊
如要進一步瞭解 Chrome 開發人員工具,請參閱說明文件。