Chrome Extension MV3迁移报错：Worker未定义及Service Worker注册失败

遇到的错误 #

• Service Worker注册失败（Service worker registration failed）
• 未捕获引用错误：Worker未定义（Uncaught ReferenceError: Worker is not defined）

用户提供的配置与代码 #

manifest.json配置

{
  "manifest_version": 3,
  "name": "Blah",
  "description": "Blah",
  "version": "1.0.0",
  "minimum_chrome_version": "93",
  "action": {
    "default_icon": "logo.png",
    "default_popup": "popup.html"
  },
  "background": {
    "service_worker": "js/background.js"
  },
  "content_scripts": [
    {
      "matches": ["file://*/*", "http://*/*", "https://*/*"],
      "js": ["js/content.js"],
      "run_at": "document_start",
      "all_frames": true
    }
  ],
  "icons": {
    "16": "icon-16.png",
    "48": "icon-48.png",
    "128": "icon-128.png"
  },
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'; worker-src 'self'"
  },
  "permissions": [
    "scripting",
    "clipboardWrite",
    "tabs",
    "activeTab",
    "notifications",
    "webRequest",
    "proxy",
    "storage",
    "unlimitedStorage",
    "alarms"
  ],
  "host_permissions": [
    "http://*/",
    "https://*/",
    "<all_urls>"
  ],
  "web_accessible_resources": [
    {
      "resources": ["js/injected.js"],
      "matches": ["*://*/*"]
    }
  ]
}

background.js脚本

import { browser } from "webextension-polyfill-ts";
import { Request } from "@src/types";
import Extension from "./extension";

const app: Extension = new Extension();

try {
  app.initialize().then(async () => {
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    browser.runtime.onMessage.addListener(async (request: Request, _) => {
      try {
        const res = await app.handle(request);
        return [null, res];
      } catch (e: any) {
        return [e.message, null];
      }
    });

} catch (error) {
  console.log("Error in backgound!!1");
}

问题排查与解决方案 #

1. Service Worker注册失败问题 #

核心原因与修复

• 语法错误：你的background脚本存在未闭合的代码块——app.initialize().then(...)的回调函数缺少});来结束，这会直接导致代码解析失败，引发注册失败。修复后代码：

import { browser } from "webextension-polyfill-ts";
import { Request } from "@src/types";
import Extension from "./extension";

const app: Extension = new Extension();

try {
  app.initialize().then(async () => {
    browser.runtime.onMessage.addListener(async (request: Request, _) => {
      try {
        const res = await app.handle(request);
        return [null, res];
      } catch (e: any) {
        return [e.message, null];
      }
    });
  }); // 补上缺失的闭合括号
} catch (error) {
  console.log("Error in background!!1");
}

• 路径验证：确认js/background.js在扩展包中的实际路径，检查打包工具是否篡改了文件位置，避免路径拼写错误。
• CSP优化：当前CSP配置可简化为更符合MV3安全规范的写法，避免潜在冲突：

"content_security_policy": {
  "extension_pages": "script-src 'self'; worker-src 'self'; object-src 'none'"
}

2. Worker未定义问题 #

MV3的Service Worker本身属于Worker环境，不支持直接创建嵌套Worker，如果你的Extension类或initialize方法中使用了new Worker(...)，需替换为以下方案：

• 若需执行页面相关任务：使用chrome.scriptingAPI注入脚本到目标页面，替代Worker功能；
• 若需后台任务：直接在Service Worker中同步/异步执行，无需额外创建Worker；
• 特殊场景必须用独立Worker：将Worker文件路径通过chrome.runtime.getURL()获取，写法为new Worker(chrome.runtime.getURL('js/your-worker.js'))，同时确保该文件在web_accessible_resources中配置（若需页面访问），但注意此方式在MV3中存在部分限制，优先推荐前两种方案。

额外检查项 #

• 确保测试用Chrome版本不低于minimum_chrome_version设置的93；
• 若使用打包工具（如Webpack），需确保Service Worker入口未被编译为依赖DOM环境的代码（Service Worker无法访问window、document等对象）；
• webRequest权限已配合host_permissions的<all_urls>配置，权限部分无问题。

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