Manifest V3 中的 offscreen 文档

Manifest V3 的 service worker 没有 DOM。当后台逻辑需要解析 DOM、播放音频、访问剪贴板，或者使用其他只在 window 中才有的 API 时，Chrome 给出的方案是 offscreen 文档：一个通过 chrome.offscreen 按需创建的不可见扩展页面。

准备工作

在 manifest.json 中申请权限：

manifest.json

{
  "permissions": ["offscreen"]
}

offscreen 页面并不是 manifest 入口，所以要通过 pages/ 特殊文件夹来声明，Extension.js 会像处理其他 HTML 入口一样把它编译出来：

pages/
└── offscreen.html

pages/offscreen.html

<!doctype html>
<html>
  <body>
    <script src="./offscreen.ts" type="module"></script>
  </body>
</html>

创建、复用、关闭

Chrome 每个扩展只允许存在一个 offscreen 文档，已经存在时再调用 createDocument 会抛错。可靠的写法是一个先检查是否已有文档的 ensure 函数：

background.ts

let creating: Promise<void> | null = null;

async function ensureOffscreen() {
  const contexts = await chrome.runtime.getContexts({
    contextTypes: ["OFFSCREEN_DOCUMENT" as chrome.runtime.ContextType],
  });
  if (contexts.length > 0) return;

  if (!creating) {
    creating = chrome.offscreen.createDocument({
      url: "pages/offscreen.html",
      reasons: [chrome.offscreen.Reason.DOM_PARSER],
      justification: "Parse HTML strings that the service worker cannot",
    });
  }
  await creating;
  creating = null;
}

这里的 creating 锁很关键：两个事件可能在文档还没创建好之前同时进入 ensureOffscreen，第二次 createDocument 调用就会抛错。工作做完后记得关闭它，以释放内存：

await chrome.offscreen.closeDocument();

选择一个 reason

reasons 数组告诉 Chrome 这个文档为何存在。常见取值：

Reason	用途
`DOM_PARSER`	解析或净化 HTML 字符串
`AUDIO_PLAYBACK`	在后台播放声音
`CLIPBOARD`	读写剪贴板
`DOM_SCRAPING`	从已渲染的标记中抓取数据
`BLOBS`	创建并管理 blob URL
`USER_MEDIA`	通过 getUserMedia 进行录制

有一个行为值得了解：使用 AUDIO_PLAYBACK 时，Chrome 会在音频停止播放约 30 秒后自动关闭该文档。其他 reason 下，文档会一直存在，直到你主动关闭它或扩展被卸载。

在后台访问剪贴板

写入剪贴板是使用 offscreen 文档最常见的理由。navigator.clipboard 挂在 window 上，而 Manifest V3 的 service worker 没有 window，所以写入必须发生在一个真实页面里。申请权限并给出对应的 reason：

manifest.json

{
  "permissions": ["offscreen", "clipboardWrite"]
}

构建 offscreen 页面时，加上一个供 copy 命令使用的 textarea：

pages/offscreen.html

<!doctype html>
<html>
  <body>
    <textarea id="clipboard-buffer"></textarea>
    <script src="./offscreen.ts" type="module"></script>
  </body>
</html>

pages/offscreen.ts

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.target !== "offscreen" || message.type !== "copy") return;

  const buffer = document.getElementById("clipboard-buffer") as HTMLTextAreaElement;
  buffer.value = message.text;
  buffer.select();
  document.execCommand("copy");
  sendResponse({ ok: true });
});

然后从 service worker 把文本发过去：

background.ts

async function copyToClipboard(text: string) {
  await ensureOffscreen();
  await chrome.runtime.sendMessage({ target: "offscreen", type: "copy", text });
}

这种场景下，给 createDocument 传入 chrome.offscreen.Reason.CLIPBOARD。 document.execCommand("copy") 才是这里能用的调用。更新的 navigator.clipboard.writeText 需要一个获得焦点的文档，而 offscreen 文档永远不会获得焦点。读取剪贴板需要 clipboardRead 权限，以及同一个文档。内容脚本，或者用户自己打开的扩展页面，都不需要这一套。它们都有真实的 window，所以在一次用户手势之后，navigator.clipboard.writeText 就能工作。

Extension.js 会帮你打包这个页面

chrome.offscreen.createDocument 接收的是一个 URL 字符串，而不是 import。Extension.js 会在构建期读取这个字符串，把该 HTML 页面以及页面加载的一切都加入产物。哪怕只有 service worker 提到过这个页面，它同样会出现在 dist/ 里。这个字符串必须是纯字面量才行。在运行时拼出来的 URL 对构建不可见，页面会被漏掉。

与 offscreen 文档通信

offscreen 文档使用标准的 runtime 消息机制。给消息加上范围标识，让其他界面可以直接忽略：

pages/offscreen.ts

chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
  if (message.target !== "offscreen") return;
  const doc = new DOMParser().parseFromString(message.html, "text/html");
  sendResponse({ title: doc.title });
  return true;
});

Firefox

Firefox 没有实现 chrome.offscreen。它的 Manifest V3 后台是以事件页面形式运行的，本身就具备 DOM 访问能力，所以同样的 DOM 工作可以直接在 Firefox 的后台脚本里完成。可以使用浏览器专属的 manifest 字段，再加上能力检测（typeof chrome.offscreen !== "undefined"）来分支处理。

Introduction

Browser extension fundamentals

Getting started

模板

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Manifest V3 中的 offscreen 文档

准备工作

创建、复用、关闭

选择一个 reason

在后台访问剪贴板

Extension.js 会帮你打包这个页面

与 offscreen 文档通信

Firefox

延伸阅读

​准备工作

​创建、复用、关闭

​选择一个 reason

​在后台访问剪贴板

​Extension.js 会帮你打包这个页面

​与 offscreen 文档通信

​Firefox

​延伸阅读

准备工作

创建、复用、关闭

选择一个 reason

在后台访问剪贴板

Extension.js 会帮你打包这个页面

与 offscreen 文档通信

Firefox

延伸阅读