迁移到 Service Worker

使用 Service Worker 替换背景或事件页面

注意：Chrome 88 或更高版本通常支持 Manifest V3。如需了解更高版本的 Chrome 中添加的扩展程序功能，请参阅 API 参考文档以获取支持信息。如果您的扩展程序需要特定的 API，您可在清单文件中指定最低 Chrome 版本。

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

自推出以来，后台网页一直是扩展程序的基本组成部分。简单来说，后台网页提供了一种独立于其他任何窗口或标签页的环境。这样，扩展程序就可以观察事件并响应事件。

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

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

在某些情况下，您会看到称为“后台脚本”的扩展程序 Service Worker。尽管扩展 Service Worker 确实在后台运行，但通过暗示功能完全相同，调用后台脚本有一定的误导性。区别将在下面进行介绍。

与后台页面相比的变化

Service Worker 与后台页面存在很多差异。

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

需要进行的更改

您需要对代码进行一些调整，以考虑后台脚本和 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"。如需了解详情，请参阅 Extension Service Worker 基础知识

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

某些扩展程序需要访问 DOM 和窗口对象，而无需在视觉上打开新的窗口或标签页。Offscreen API 支持这类使用情形，因为这类 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 转换为其他类型

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

也可以将其通话移至屏幕外文档。例如，如需将之前存储在 localStorage 中的数据迁移到其他机制，请使用以下代码：

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

Web Storage API 在扩展程序中的工作原理也存在一些细微差别。如需了解详情，请参阅存储和 Cookie。

同步注册监听器

异步注册监听器（例如在 promise 或 callback 中）注册并不一定能在 Manifest V3 中有效。请参考以下代码。

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);

要点：如果您之前使用 XMLHttpRequest() 或 fetch() 检索可执行代码，则现在不能再检索。所有可执行代码都必须是扩展程序软件包的一部分。如需了解详情，请参阅提高扩展程序的安全性。

保留状态

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 保持活跃状态

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

• fetch() 请求的用时可能会超过 5 分钟（例如，网络连接状况不佳的情况下下载大量内容）。
• 复杂的异步计算需要超过 30 秒。

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

以下示例展示了一个 waitUntil() 辅助函数，该函数会在给定 promise 解析之前使 Service Worker 保持活跃状态：

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

waitUntil(someExpensiveCalculation());

要点：WECG 中目前正在讨论一个类似于 waitUntil() 的官方 API。如需了解详情，请参阅 GitHub 上的讨论。

使 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'];
}