调试扩展程序

扩展程序可以访问与网页相同的 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.

“清单键无效”错误对话框。

如果清单键无效，扩展程序将无法加载，但 Chrome 会提示您如何解决该问题。

请撤消这项更改并输入无效权限，看看会发生什么情况。 将 "activeTab" 权限更改为小写的 "activetab"：

manifest.json:

{
  ...
  "permissions": ["activeTab", "scripting", "storage"],
  "permissions": ["activetab", "scripting", "storage"],
  ...
}

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

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

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

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

如何清除扩展程序错误。

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

调试 Service Worker

查找日志

Service Worker 将默认颜色设置为 storage，并将其记录到控制台。要查看此日志，请选择检查视图旁边的蓝色链接，以打开 Chrome 开发者工具面板。

Chrome DevTools 面板中的 Service Worker 日志。

要点：检查 Service Worker 使其保持活跃状态。为了确保您的扩展程序在 Service Worker 终止时能够正常运行，请记得关闭开发者工具。

定位错误

我们通过将 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 开发者工具。

实际错误显示如下：

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

未捕获的 TypeError 消息。

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

检查 Service Worker 的状态

要确定 Service Worker 何时唤醒以执行任务，请按以下步骤操作：

1. 复制位于“检查视图”上方的扩展程序 ID。

   

   “扩展程序管理”页面中的扩展程序 ID。

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

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

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

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

在 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

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

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

开发者工具显示弹出式错误。

错误 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 旁边的下拉箭头，然后选择扩展程序。

未捕获 ReferenceError：没有定义颜色。

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

监控网络请求

弹出式窗口通常会发出所有必需的网络请求，即使是最快速的开发者也能打开开发者工具。如需查看这些请求，请从“网络”面板内刷新。它会重新加载弹出式窗口，而不会关闭开发者工具面板。

在“网络”面板中刷新，即可查看弹出式网络请求。

声明权限

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

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

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

深入阅读

通过阅读相关文档，详细了解 Chrome 开发者工具。