迁移到 Service Worker

使用 Service Worker 替换后台页面或事件页面

Service Worker 会替换扩展程序的后台页面或事件页面，以确保后台代码不会保留在主线程中。这样，扩展程序便可以仅在需要时运行，从而节省资源。

自扩展程序推出以来，后台页面一直是扩展程序的基本组件。简而言之，后台页面提供了一个独立于任何其他窗口或标签页的环境。这样，扩展程序便可以观察事件并采取行动来响应事件。

本页面介绍了将后台页面转换为扩展程序 Service Worker 的任务。如需大致了解扩展程序 Service Worker，请参阅教程 使用 Service Worker 处理事件 以及部分 关于扩展程序 Service Worker。

后台脚本与扩展程序 Service Worker 之间的区别

在某些情况下，您会看到扩展程序 Service Worker 被称为“后台脚本”。虽然扩展程序 Service Worker 确实在后台运行，但将其称为后台脚本有点误导，因为它暗示了它们具有相同的功能。区别将在下面进行介绍。

与后台页面的变化

Service Worker 与后台页面有许多不同之处。

  • 它们在主线程之外运行，这意味着它们不会干扰扩展程序内容。
  • 它们具有特殊功能，例如拦截扩展程序来源上的 fetch 事件，例如来自工具栏弹出式窗口的事件。
  • 它们可以通过 Clients 接口 与其他上下文进行通信和互动。

您需要做出的更改

您需要进行一些代码调整，以考虑后台脚本和 Service Worker 的运行方式之间的差异。首先，在清单文件中指定 Service Worker 的方式与指定后台脚本的方式不同。此外：

  • 由于它们无法访问 DOM 或 window 接口，因此您需要将此类调用移至其他 API 或屏幕外文档中。
  • 不应注册事件监听器来响应返回的 promise 或在事件回调中注册。
  • 由于它们与 XMLHttpRequest() 不向后兼容，因此您需要将对此接口的调用替换为对 fetch() 的调用。
  • 由于它们在不使用时会终止，因此您需要保留应用状态，而不是依赖于全局变量。终止 Service Worker 还会提前结束计时器。您需要将它们替换为闹钟。

本页面详细介绍了这些任务。

更新清单中的“background”字段

在 Manifest V3 中，后台页面会被 Service Worker 替换。清单更改如下所示。

  • 在 manifest.json 中，将 "background.scripts" 替换为 "background.service_worker"。请注意，"service_worker" 字段接受字符串，而不是字符串数组。
  • 从 manifest.json 中移除 "background.persistent"。
Manifest V2
{
  ...
  "background": {
    "scripts": [
      "backgroundContextMenus.js",
      "backgroundOauth.js"
    ],
    "persistent": false
  },
  ...
}
Manifest V3
{
  ...
  "background": {
    "service_worker": "service_worker.js",
    "type": "module"
  }
  ...
}

"service_worker" 字段接受单个字符串。只有在使用 ES 模块（使用 import 关键字）时，才需要 "type" 字段。其值始终为 "module"。如需了解详情，请参阅扩展程序 Service Worker 基础知识

将 DOM 和窗口调用移至屏幕外文档

某些扩展程序需要访问 DOM 和窗口对象，而无需以可视方式打开新窗口或标签页。Offscreen API 通过打开和关闭与扩展程序打包在一起的未显示文档来支持这些用例，而不会中断用户体验。除了消息传递之外，屏幕外文档不与其他扩展程序上下文共享 API，但充当扩展程序与之互动的完整网页。

如需使用 Offscreen API，请通过 Service Worker 创建屏幕外文档。

chrome.offscreen.createDocument({
  url: chrome.runtime.getURL('offscreen.html'),
  reasons: ['CLIPBOARD'],
  justification: 'testing the offscreen API',
});

在屏幕外文档中，执行您之前在后台脚本中运行的任何操作。例如，您可以复制在宿主页面上选择的文本。

let textEl = document.querySelector('#text');
textEl.value = data;
textEl.select();
document.execCommand('copy');

使用 消息传递 在屏幕外文档和扩展程序 Service Worker 之间进行通信。

将 localStorage 转换为其他类型

Service Worker 中无法使用 Web 平台的 Storage 接口（可从 window.localStorage 访问）。如需解决此问题，请执行以下操作之一。首先，您可以将其替换为对其他存储机制的调用。chrome.storage.local 命名空间将满足大多数用例，但 其他选项 可用。

您还可以将其调用移至屏幕外文档。例如，如需将之前存储在 localStorage 中的数据迁移到其他机制，请执行以下操作：

  1. 使用转换例程和 runtime.onMessage 处理程序创建屏幕外文档。
  2. 向屏幕外文档添加转换例程。
  3. 在扩展程序 Service Worker 中，检查 chrome.storage 以获取您的数据。
  4. 如果找不到您的数据，请创建屏幕外文档并调用 runtime.sendMessage() 以启动转换例程。
  5. 在您添加到屏幕外文档的 runtime.onMessage 处理程序中，调用转换例程。

此外，Web 存储 API 在扩展程序中的工作方式也存在一些细微差别。如需了解详情，请参阅存储空间和 Cookie。

同步注册监听器

在 Manifest V3 中，异步注册监听器（例如在 promise 或回调中）不保证有效。请考虑以下代码。

chrome.storage.local.get(["badgeText"], ({ badgeText }) => {
  chrome.browserAction.setBadgeText({ text: badgeText });
  chrome.browserAction.onClicked.addListener(handleActionClick);
});

这适用于持久性后台页面，因为该页面会持续运行，并且永远不会重新初始化。在 Manifest V3 中，Service Worker 会在分派事件时重新初始化。这意味着，当事件触发时，监听器不会注册（因为它们是异步添加的），并且事件会被错过。

请改为将事件监听器注册移至脚本的顶层。这样可以确保 Chrome 能够立即找到并调用操作的点击处理程序，即使您的扩展程序尚未完成执行其启动逻辑也是如此。

chrome.action.onClicked.addListener(handleActionClick);

chrome.storage.local.get(["badgeText"], ({ badgeText }) => {
  chrome.action.setBadgeText({ text: badgeText });
});

将 XMLHttpRequest() 替换为全局 fetch()

无法从 Service Worker、扩展程序或其他位置调用 XMLHttpRequest()。将后台脚本中对 XMLHttpRequest() 的调用替换为对 全局 fetch() 的调用。

XMLHttpRequest()
const xhr = new XMLHttpRequest();
console.log('UNSENT', xhr.readyState);

xhr.open('GET', '/api', true);
console.log('OPENED', xhr.readyState);

xhr.onload = () => {
    console.log('DONE', xhr.readyState);
};
xhr.send(null);
fetch()
const response = await fetch('https://www.example.com/greeting.json'')
console.log(response.statusText);

保留状态

Service Worker 是短暂的，这意味着它们可能会在用户的浏览器会话期间重复启动、运行和终止。这也意味着，由于之前的上下文已关闭，因此全局变量中的数据不会立即可用。如需解决此问题，请使用存储 API 作为可信来源。以下示例将展示如何执行此操作。

以下示例使用全局变量来存储名称。在 Service Worker 中，此变量可能会在用户的浏览器会话期间多次重置。

Manifest V2 后台脚本
let savedName = undefined;

chrome.runtime.onMessage.addListener(({ type, name }) => {
  if (type === "set-name") {
    savedName = name;
  }
});

chrome.browserAction.onClicked.addListener((tab) => {
  chrome.tabs.sendMessage(tab.id, { name: savedName });
});

对于 Manifest V3，请将全局变量替换为对 Storage API 的调用。

Manifest V3 Service Worker
chrome.runtime.onMessage.addListener(({ type, name }) => {
  if (type === "set-name") {
    chrome.storage.local.set({ name });
  }
});

chrome.action.onClicked.addListener(async (tab) => {
  const { name } = await chrome.storage.local.get(["name"]);
  chrome.tabs.sendMessage(tab.id, { name });
});

将计时器转换为闹钟

通常使用 setTimeout() 或 setInterval() 方法来使用延迟或定期操作。不过，这些 API 在 Service Worker 中可能会失败，因为每当 Service Worker 终止时，计时器都会被取消。

Manifest V2 后台脚本
// 3 minutes in milliseconds
const TIMEOUT = 3 * 60 * 1000;
setTimeout(() => {
  chrome.action.setIcon({
    path: getRandomIconPath(),
  });
}, TIMEOUT);

请改为使用 Alarms API。与其他监听器一样，闹钟监听器应在脚本的顶层注册。

Manifest V3 Service Worker
async function startAlarm(name, duration) {
  await chrome.alarms.create(name, { delayInMinutes: 3 });
}

chrome.alarms.onAlarm.addListener(() => {
  chrome.action.setIcon({
    path: getRandomIconPath(),
  });
});

保持 Service Worker 处于活跃状态

根据定义，Service Worker 是事件驱动型的，并且会在不活动时终止。这样，Chrome 就可以优化扩展程序的性能和内存消耗。如需了解详情，请参阅我们的 Service Worker 生命周期文档。在特殊情况下，可能需要采取其他措施来确保 Service Worker 保持更长时间的活跃状态。

保持 Service Worker 处于活跃状态，直到长时间运行的操作完成

在不调用扩展程序 API 的长时间运行的 Service Worker 操作期间，Service Worker 可能会在操作中途关闭。例如：

  • A fetch() 请求 可能会花费超过 5 分钟的时间（例如，在连接可能较差的情况下下载大型文件）。
  • 复杂的异步计算花费超过 30 秒。

如需在这种情况下延长 Service Worker 的生命周期，您可以定期调用一个简单的扩展程序 API 来重置超时计数器。 请注意，这仅适用于特殊情况，在大多数情况下，通常有更好、更符合平台习惯的方式来实现相同的结果。

以下示例展示了一个 waitUntil() 辅助函数，该函数可让 Service Worker 保持活跃状态，直到给定的 promise 解析完毕：

async function waitUntil(promise) {
  const keepAlive = setInterval(chrome.runtime.getPlatformInfo, 25 * 1000);
  try {
    await promise;
  } finally {
    clearInterval(keepAlive);
  }
}

waitUntil(someExpensiveCalculation());

保持 Service Worker 持续处于活跃状态

在极少数情况下，需要无限期地延长生命周期。我们已将企业和教育机构确定为最大的用例，并且专门允许在此处使用，但我们一般不支持此功能。在这些特殊情况下，可以通过定期调用简单的扩展程序 API 来保持 Service Worker 处于活跃状态。请务必注意，此建议仅适用于在受管理设备上运行的扩展程序，以用于企业或教育用例。在其他情况下，不允许使用此功能，Chrome 扩展程序团队保留在未来对此类扩展程序采取行动的权利。

使用以下代码段可让 Service Worker 保持活跃状态：

/**
 * Tracks when a service worker was last alive and extends the service worker
 * lifetime by writing the current time to extension storage every 20 seconds.
 * You should still prepare for unexpected termination - for example, if the
 * extension process crashes or your extension is manually stopped at
 * chrome://serviceworker-internals. 
 */
let heartbeatInterval;

async function runHeartbeat() {
  await chrome.storage.local.set({ 'last-heartbeat': new Date().getTime() });
}

/**
 * Starts the heartbeat interval which keeps the service worker alive. Call
 * this sparingly when you are doing work which requires persistence, and call
 * stopHeartbeat once that work is complete.
 */
async function startHeartbeat() {
  // Run the heartbeat once at service worker startup.
  runHeartbeat().then(() => {
    // Then again every 20 seconds.
    heartbeatInterval = setInterval(runHeartbeat, 20 * 1000);
  });
}

async function stopHeartbeat() {
  clearInterval(heartbeatInterval);
}

/**
 * Returns the last heartbeat stored in extension storage, or undefined if
 * the heartbeat has never run before.
 */
async function getLastHeartbeat() {
  return (await chrome.storage.local.get('last-heartbeat'))['last-heartbeat'];
}