Chrome Manifest V3后台下载大文件：navigator.serviceWorker未定义

问题根源 #

Chrome扩展的上下文（popup、content script、后台service worker）和普通网页逻辑不同，普通网页通过navigator.serviceWorker访问service worker的方式在扩展中不适用。扩展需要使用Chrome专属API操作service worker，且Background Fetch的调用规则也有差异。

解决方案步骤 #

1. 配置Manifest V3

扩展必须使用Manifest V3，并正确声明后台service worker、必要权限和目标主机权限：

{
  "manifest_version": 3,
  "name": "后台下载工具",
  "version": "1.0",
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["downloads", "storage"],
  "host_permissions": ["https://your-external-source-domain.com/*"]
}

• background字段指定后台service worker文件路径
• downloads权限用于后续将下载文件保存到本地
• host_permissions添加你需要下载的外部源域名

2. 在后台Service Worker中实现Background Fetch

扩展的service worker上下文可直接通过self.registration.backgroundFetch调用API，无需依赖navigator.serviceWorker：

// 监听来自前端的下载请求
chrome.runtime.onMessage.addListener(async (message, sender, sendResponse) => {
  if (message.action !== "start-bg-download") return;

  try {
    // 初始化后台下载任务
    const bgFetchTask = await self.registration.backgroundFetch.fetch(
      "large-file-download-task", // 唯一任务ID
      [message.downloadUrl], // 目标资源URL
      {
        title: "大文件下载中",
        icons: [{ src: "/icons/icon-192.png", sizes: "192x192", type: "image/png" }],
        downloadTotal: message.fileSize // 可选：传入文件总大小用于进度计算
      }
    );

    // 监听下载进度
    bgFetchTask.addEventListener("progress", (event) => {
      const progress = Math.round((event.downloaded / event.total) * 100);
      // 发送进度到popup展示
      chrome.runtime.sendMessage({ action: "download-progress", progress });
    });

    // 监听下载完成
    bgFetchTask.addEventListener("success", async () => {
      const records = await bgFetchTask.matchAll();
      const blob = await records[0].blob();
      // 用chrome.downloads API保存文件到本地
      chrome.downloads.download({
        url: URL.createObjectURL(blob),
        filename: "target-file.zip"
      });
      chrome.runtime.sendMessage({ action: "download-complete" });
    });

    // 监听下载失败
    bgFetchTask.addEventListener("failure", () => {
      chrome.runtime.sendMessage({ action: "download-failed" });
    });

    sendResponse({ status: "started" });
  } catch (err) {
    sendResponse({ status: "failed", error: err.message });
  }
  return true; // 保持消息通道开放以异步返回结果
});

3. 从Popup/Content Script触发下载

前端页面无法直接调用Background Fetch，需通过chrome.runtime.sendMessage给后台发指令：

// popup.js示例
document.getElementById("start-download-btn").addEventListener("click", () => {
  const downloadUrl = "https://your-external-source-domain.com/large-file.zip";
  const fileSize = 524288000; // 示例：500MB，根据实际文件大小填写

  chrome.runtime.sendMessage(
    { action: "start-bg-download", downloadUrl, fileSize },
    (res) => {
      if (res.status === "started") {
        alert("后台下载已启动");
      } else {
        alert(`启动失败：${res.error}`);
      }
    }
  );
});

关键注意事项 #

• 仅支持Manifest V3，Manifest V2的页面型后台无法使用Background Fetch
• 后台service worker无DOM环境，所有逻辑必须基于事件驱动
• 测试时可通过扩展管理页的「Service Worker」入口查看运行日志
• 若无需保留下载的Blob，也可直接在chrome.downloads.download中传入原URL（需确保主机权限已配置）

内容的提问来源于stack exchange，提问作者Avi