扩展程序可以访问与网页相同的 Chrome 开发者工具。为了成为调试扩展程序的专家,您需要了解如何查找不同扩展程序组件的日志和错误。本教程介绍了调试扩展程序的基本技巧。
准备工作
本指南假定您具备基本的 Web 开发经验。我们建议您阅读开发基础知识,以简要了解扩展程序开发工作流。设计界面介绍了扩展程序中提供的界面元素。
中断扩展程序
本教程一次中断一个扩展程序组件,然后演示如何修复该组件。请务必先撤消在一个部分中引入的 bug,然后再继续下一部分。首先在 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=8&hl=nb)
如果清单键无效,扩展程序将无法加载,但 Chrome 会提示您如何解决该问题。
请撤消这项更改并输入无效权限,看看会发生什么情况。
将 "activeTab"
权限更改为小写的 "activetab"
:
manifest.json:
{
...
"permissions": ["activeTab", "scripting", "storage"],
"permissions": ["activetab", "scripting", "storage"],
...
}
保存该扩展程序,然后尝试重新加载。这次应该能够成功加载。在扩展程序管理页面中,您会看到三个按钮:详细信息、移除和错误。出现错误时,错误按钮标签会变为红色。点击错误按钮可查看以下错误:
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=8&hl=nb)
在继续操作之前,请将权限改回去,点击右上角的全部清除以清除日志,并重新加载该扩展程序。
![“全部清除”按钮](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/clear-button-2f67dd9230519.png?authuser=8&hl=nb)
调试 Service Worker
查找日志
Service Worker 将默认颜色设置为 storage,并将其记录到控制台。要查看此日志,请选择检查视图旁边的蓝色链接,以打开 Chrome 开发者工具面板。
![打开扩展程序 Service Worker 的开发者工具。](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/opening-devtools-the-ex-685e204e20773.png?authuser=8&hl=nb)
定位错误
我们通过将 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=8&hl=nb)
实际错误显示如下:
Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')
![未捕获的类型错误:无法读取未定义错误消息的属性](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/uncaught-typeerror-canno-45ae014961338.png?authuser=8&hl=nb)
请撤消我们引入的 bug,点击右上角的全部清除,然后重新加载该扩展程序。
检查 Service Worker 的状态
要确定 Service Worker 何时唤醒以执行任务,请按以下步骤操作:
- 复制位于“检查视图”上方的扩展程序 ID。
“扩展程序管理”页面中的扩展程序 ID。 - 在浏览器中打开您的清单文件。例如:
text chrome-extension://YOUR_EXTENSION_ID/manifest.json
- 检查文件。
- 转到 Application(应用)面板。
- 转到 Service Workers 窗格。
要测试您的代码,请使用 status 旁边的链接启动或停止 Service Worker。
![Application 面板中的 Service Worker 状态](https://developer.chrome.google.cn/docs/extensions/get-started/tutorial/debug/image/start-stop-service-worker.png?auto=format&w=845&authuser=8&hl=nb)
此外,如果您更改了 Service Worker 代码,可以点击 Update 或 skipWaiting 立即应用更改。
![Application 面板中的 Service Worker 状态](https://developer.chrome.google.cn/docs/extensions/get-started/tutorial/debug/image/update-or-skipwaiting.png?auto=format&w=845&authuser=8&hl=nb)
调试弹出式窗口
现在,该扩展程序已正确初始化,下面我们注释掉下面突出显示的行来破坏弹出式窗口:
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
});
});
});
返回“扩展程序管理”页面。错误按钮会重新出现。点击该日志即可查看新日志。它会显示以下错误消息:
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=8&hl=nb)
您可以通过检查弹出式窗口来打开该弹出式窗口的开发者工具。
![显示弹出式错误的开发者工具。](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/devtools-displaying-popup-0ed24fd80361a.png?authuser=8&hl=nb)
错误 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=8&hl=nb)
如需在内容脚本中使用开发者工具,请点击 top 旁边的下拉箭头,然后选择扩展程序。
![未捕获 ReferenceError:没有定义颜色](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/uncaught-referenceerror-e5847be3a7de9.png?authuser=8&hl=nb)
错误消息显示未定义 colors
。扩展程序必须未正确传递变量。更正注入的脚本,以将颜色变量传递到代码中。
监控网络请求
弹出式窗口通常会发出所有必需的网络请求,即使是最快速的开发者也能打开开发者工具。如需查看这些请求,请从“网络”面板内刷新。它会重新加载弹出式窗口,而不会关闭开发者工具面板。
![在“网络”面板内刷新以查看弹出式网络请求](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/debug/image/refresh-inside-network-p-43993068e650e.gif?authuser=8&hl=nb)
声明权限
某些扩展程序 API 需要权限。请参阅权限一文和 Chrome API,确保扩展程序在清单中请求正确的权限。
{
"name": "Broken Background Color",
...
"permissions": [
"activeTab",
"declarativeContent",
"storage"
],
...
}
深入阅读
通过阅读相关文档,详细了解 Chrome 开发者工具。