调试扩展程序

扩展程序可以访问与网页相同的 Chrome 开发者工具。要成为扩展程序调试专家，您需要了解如何查找不同扩展程序组件的日志和错误。本教程介绍了调试扩展程序的基本技巧。

准备工作

本指南假定您具备基本的 Web 开发经验。建议您阅读 开发基础知识：简要介绍扩展程序的开发工作流程。 设计界面：向用户介绍 扩展程序中提供的界面元素

中断扩展程序

本教程将每次破坏一个扩展程序组件，然后演示如何修复该组件。在继续学习下一部分之前，请务必先撤消上一部分中引入的错误。首先，在 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"],
  ...
}

保存该扩展程序，然后尝试重新加载。这次它应该可以成功加载。在扩展程序中 您会看到三个按钮：详细信息、移除和错误。错误 出错时，按钮标签会变为红色。点击错误按钮可查看 出现以下错误：

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

点击“错误”按钮查找错误消息。

在继续之前，请将权限改回去，点击右上角的全部清除以清除日志，然后重新加载扩展程序。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 如何清除扩展程序错误。

。

注意：在代码编辑器中使用清单架构可确保清单具有正确的格式和必填字段。

调试 Service Worker

查找日志

Service Worker 将默认颜色设置为 storage，并将其记录到控制台。要查看此日志，请选择 Inspect views 旁边的蓝色链接，打开 Chrome DevTools 面板。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> Chrome DevTools 面板中的 Service Worker 日志。

。

要点：检查 Service Worker 可使其保持活跃状态。为确保您的扩展程序在 Service Worker 终止后正常运行，请务必关闭 DevTools。

定位错误

我们通过将 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 注册错误消息。

。

注意：如果 Service Worker 注册失败，则在修复注册 bug 之前，您将无法访问 Chrome DevTools。

实际错误出现在：

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')

未捕获 TypeError 消息。

请撤消我们引入的错误，点击右上角的全部清除，然后重新加载扩展程序。

检查 Service Worker 状态

您可以按照以下步骤确定 Service Worker 何时唤醒以执行任务：

1. 复制位于“检查视图”上方的扩展程序 ID。 <ph type="x-smartling-placeholder">

   </ph> <ph type="x-smartling-placeholder">

   </ph> “扩展程序管理”页面中的扩展程序 ID。

2. 在浏览器中打开您的清单文件。例如： text chrome-extension://YOUR_EXTENSION_ID/manifest.json
3. 检查文件。
4. 转到应用面板。
5. 转到 Service Workers 窗格。

要测试您的代码，请使用 status 旁边的链接启动或停止 Service Worker。

<ph type="x-smartling-placeholder">

</ph>

“Application”面板中的 Service Worker 状态。（点击可放大图片。）

此外，如果您更改了 Service Worker 代码，则可以点击 Update 或 skipWaiting 以立即应用更改。

<ph type="x-smartling-placeholder">

</ph>

在 Application 面板中刷新 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
    });
  });
});

返回“扩展程序管理”页面。错误按钮会再次出现。点击即可 查看新日志。它会显示以下错误消息：

Uncaught ReferenceError: tabs is not defined

显示弹出式错误的“扩展程序管理”页面。

您可以通过检查弹出式窗口来打开该弹出式窗口的开发者工具。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> DevTools 显示弹出式错误。

错误 tabs is undefined 表示扩展程序不知道在哪里注入内容脚本。 如需更正此问题，请调用 tabs.query()，然后选择使用中的标签页。

要更新代码，请点击右上角的全部清除按钮，然后重新加载 。

注意：对于显示为标签页的其他扩展程序页面（例如替换网页和整页选项）， 如需查找日志，请查看该页面或访问“Extension Management”页面。

调试内容脚本

现在，我们将更改变量“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 旁边的下拉箭头，然后选择扩展程序。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 未捕获的 ReferenceError：未定义颜色。

错误消息称 colors 未定义。扩展程序必须正确传递变量。 更正注入的脚本，以将颜色变量传递到代码中。

监控网络请求

该弹出式窗口通常会比最快的网络请求完成速度， 开发者只需打开开发者工具即可如需查看这些请求，请从“网络”面板内进行刷新。它 重新加载弹出式窗口，而不关闭开发者工具面板。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 在 Network 面板中刷新可查看弹出式网络请求。

声明权限

某些扩展程序 API 需要权限。请参阅权限一文和 Chrome API确保扩展程序在清单中请求正确的权限。

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

要点：要对外部服务器进行 fetch() 调用，您必须将相应网址声明为主机权限。

深入阅读

如需详细了解 Chrome 开发者工具，请参阅相关文档。