Background 脚本与 MV3 service worker

​

模板示例

​

action

npx extension@latest create my-extension --template=action

pnpx extension@latest create my-extension --template=action

yarn dlx extension@latest create my-extension --template=action

bunx extension@latest create my-extension --template=action

deno run -A npm:extension@latest create my-extension --template=action

​

ai-chatgpt

npx extension@latest create my-extension --template=ai-chatgpt

pnpx extension@latest create my-extension --template=ai-chatgpt

yarn dlx extension@latest create my-extension --template=ai-chatgpt

bunx extension@latest create my-extension --template=ai-chatgpt

deno run -A npm:extension@latest create my-extension --template=ai-chatgpt

​

Background 能力

​

Background 脚本支持

​

Background 脚本声明示例

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "background": {
    "service_worker": "./scripts/background.ts"
  }
}

​

开发期行为

• Extension.js 会跟踪 service worker 与源码的变更，并可以触发扩展的硬重载。
• 影响 background 入口的 manifest 变更可能触发需要重启的诊断信息。
• 浏览器启动插件会按目标浏览器（Chromium/Firefox）应用各自的硬重载策略。
• Extension.js 对结构性入口变更比对普通模块编辑要更严格。

​

Firefox：将 service worker 翻译为 event page

​

Chromium：将 scripts 翻译为 service worker

​

MV3 service worker 生命周期

• 内存中的状态可能在事件之间消失。
• 设计长时间运行的工作时要围绕事件，而不是依赖进程永不退出。
• 启动开销应当小而可预测。
• 你的代码应当从存储中恢复重要状态，或者安全地重新计算。

​

输出行为

• background/service_worker.js
• background/scripts.js

​

Module 与 classic 注意事项

• background.type: "module" 使用 module worker 语义。
• Classic service worker 模式使用基于 importScripts 的 chunk 加载行为。
• 避免在启动时就必须立即加载的 background 代码中使用动态 import。

​

运行时加载的文件

• classic service worker 的 importScripts(...) 依赖。 字符串字面量参数会相对于输出的 worker 位置递归解析（一个依赖自己也可以调用 importScripts），因此即使 worker 被移动到 background/service_worker.js，相对于 worker 的 URL 仍然有效。由 wasm-bindgen 胶水代码加载的 WebAssembly 同级文件（*_bg.wasm）会与它的加载器一起发布。
• chrome.scripting.executeScript({files: [...]}) 与 insertCSS({files: [...]}) 的载荷。 只在 files: 数组中被引用、而没有在 manifest 的 content_scripts 中声明的文件，会按其扩展根目录下的路径原样复制。

​

推荐架构

• 让 background 入口保持精简，把功能逻辑放进共享模块。
• 把 background 上下文当作消息通信、存储访问和浏览器 API 调用的中心协调点。
• 从存储中恢复持久状态，不要假设 background 脚本始终运行。
• 使用 alarms、显式的事件监听器和小而专注的功能模块，而不是一条庞大的启动路径。

​

常见错误

• 把 service worker 当成永远运行的服务器进程。
• 把关键状态只保留在内存里。
• 在每次事件唤醒时都执行昂贵的启动工作。
• 把过多功能逻辑放在 popup 或 content script 代码中，而它们其实需要 background 级别的浏览器 API 访问。

​

最佳实践

• MV3 优先的扩展应优先使用 background.service_worker。
• 让 background 入口文件保持小巧，把逻辑委派到共享模块。
• 避免在 service worker 中进行昂贵的启动工作；在安全的前提下延迟初始化。
• 在开发流程中把 manifest 中 background 字段的编辑视为结构性变更。
• 通过经过校验的消息处理器路由特权操作。
• 把持久设置和缓存放进浏览器存储，而不是只放在模块级变量里。

​

下一步

• 在 dev 更新行为 中了解更新结果。
• 用 存储 持久化运行时状态。
• 用 消息通信 协调上下文。
• 进一步了解 开发中的 JavaScript。
• 继续阅读 content script。
• 在 Manifest V3 故障排查 中排查 service worker 行为问题。