在 background 上下文中运行扩展级别的逻辑,并明确支持 Manifest V2(MV2)background 脚本与 Manifest V3(MV3)service worker。
Extension.js 从 manifest.json 读取 background 入口,并将其编译为专门的 background 产物。它会在开发阶段按浏览器应用相应的重载行为。
模板示例
action
一个带有 action popup 的扩展,使用 background service worker 处理浏览器事件。
仓库:extension-js/templates/action
ai-chatgpt
带有 background service worker 的 action popup,集成外部 API(ChatGPT)。
仓库:extension-js/templates/ai-chatgpt
Background 能力
Background 脚本支持
可以通过以下 manifest.json 字段声明 background 脚本:
background.type 也会影响运行时模式(module 与 classic service worker 行为之间的区别)。
Background 脚本声明示例
manifest.json 中的 background 脚本声明示例:
开发期行为
Extension.js 会跟踪 service worker 与源码的变更,并可以触发扩展的硬重载。
当 manifest 的修改添加、移除或重命名了脚本入口时,正在运行的 extension dev 会话会自行重启编译器并重新加载扩展。你不需要重启命令。从 4.1.41 之后的版本开始,脚本移到另一个 manifest 键时会话也会重启,例如把同一个文件从 background.scripts 移到 background.service_worker。
浏览器启动插件会按目标浏览器(Chromium/Firefox)应用各自的硬重载策略。
Extension.js 对结构性入口变更比对普通模块编辑要更严格。
Firefox:将 service worker 翻译为 event page
Firefox 不会运行 MV3 background.service_worker(加载这样的扩展会失败,错误为 “background.service_worker is currently disabled. Add background.scripts.” )。你不需要专门处理:对于 Firefox 构建,Extension.js 会自动把 background.service_worker 入口翻译成指向同一编译产物的 background.scripts event page。只编写一处 background.service_worker,在 Chromium 与 Firefox 上都能加载。
Chromium:将 scripts 翻译为 service worker
这个翻译在另一个方向上同样成立。在 Chromium MV3 构建里,background.scripts 数组会变成指向编译产物的 background.service_worker。
Chromium MV3 永远不会启动 background.scripts。旁边没有 service_worker 时,Chrome 151 会加载这个扩展,不显示任何错误,也不运行任何 background。因此 Extension.js 总是会从输出的 Chromium MV3 manifest 中移除 scripts 键。当源文件同时声明了两个字段时,已有的 service_worker 条目胜出。
Safari:用 background 页面,而不是 service worker
从 4.1.20 起,Safari 构建产出的是一个非持久的 background 页面。Extension.js 会把 background.service_worker 条目翻译成 background: {scripts: [...]},和它为 Firefox 做的翻译一样。
原因是在 Safari 26.5.2 上测量出来的:测试中 Manifest V3 的 service worker 从未启动过,包括用 Apple 自己的转换器构建的扩展,而 background 页面则会立即运行。WebKit 有意偏好页面形式(WebKit bug 270750 )。
在 background 脚本 顶层 有一个没有保护的、仅 Chromium
才有的调用,在 Safari 上就会抛错,Safari 随后会丢弃这个 background
上下文。你拿不到日志、拿不到重载,也看不到任何错误,扩展看上去就是死的。请保护这个调用,或者在构建期分支。
从 4.1.20 起的 Safari 构建还会对 Safari 缺少的扩展 API 发出警告,这是在你开始调试之前发现问题最省事的办法。详见 构建 Safari 扩展 。
MV3 service worker 生命周期
background.service_worker 按浏览器的 service worker 生命周期运行,而不是作为长时间运行的进程。
这意味着:
内存中的状态可能在事件之间消失。
设计长时间运行的工作时要围绕事件,而不是依赖进程永不退出。
启动开销应当小而可预测。
你的代码应当从存储中恢复重要状态,或者安全地重新计算。
只在需要 MV2 兼容的场景下使用 background.scripts。对于 MV3 优先的扩展,应把 service worker 当作浏览器 API 调用与跨上下文通信的中心协调者。
输出行为
常见的输出包括:
background/service_worker.js
background/scripts.js
具体输出取决于浏览器过滤后仍然生效的是哪个 manifest 字段。
Module 与 classic 注意事项
background.type: "module" 使用 module worker 语义。
Classic service worker 模式使用基于 importScripts 的 chunk 加载行为。
避免在启动时就必须立即加载的 background 代码中使用动态 import。
从 4.1.41 之后的版本开始,在 service worker background 中,用 import() 加载的代码会被打包进 worker 文件,因为 Chromium 只允许 service worker 在安装期间获取脚本。这个模块仍然只在第一次被导入时才运行。扩展页面和 Firefox 的 background 页面仍然保留独立的懒加载 chunk。
运行时加载的文件
有些文件从不以 import 语句的形式出现,但仍然必须随扩展一起发布。Extension.js 会把它们追踪进产物,让构建出来的扩展与在浏览器中以未打包方式加载源码时表现一致:
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 中声明的文件,会按其扩展根目录下的路径原样复制。
contentScripts.register 与 userScripts.register 的文件。 从 4.1.41 之后的版本起,这些调用以 {file: "..."} 写明的脚本,会按其扩展根目录下的路径复制。
以普通字符串保存的路径。 从 4.1.41 之后的版本起,如果脚本把一个路径保存为字符串,而这个文件存在于你项目的某个文件夹里,构建就会发布它。例如代码把一张路径表交给 fetch 或 chrome.action.setIcon:
构建以这种方式复制数据文件和媒体文件,不会以这种方式复制脚本、页面或样式表。代码在运行时拼接出来的路径不对应任何具体文件。对这样的路径,构建会打印一条写明该文件夹的警告。请把这些文件放进 public/。
按路径打开的页面的样式表。 你的代码按路径打开的页面(例如通过 chrome.runtime.getURL("/ui/options/index.html")),会连同它的脚本和样式表一起发布。从 4.1.41 之后的版本起,这些样式表通过 url() 加载的字体和图片也会一起发布。只有扩展页面加载的字体会随构建产出,但没有 web_accessible_resources 条目。
按文件注入的样式表。 从 4.1.41 之后的版本开始,由 scripting.insertCSS({files})、tabs.insertCSS({file}) 或 scripting.registerContentScripts 的 css 列表指明的样式表,会连同它通过 url() 加载的字体和图片以及它导入的样式表一起发布。在 Chrome 上,注入的样式表里的 url() 是相对于被访问的页面解析的。请把目标写成 chrome-extension://__MSG_@@extension_id__/path。构建会把样式表加载的文件列在 web_accessible_resources 下:Chromium 和 Safari 目标列出每一个文件,Firefox 目标只列出字体。Firefox 的 Manifest V3 在没有这个条目时会拦截注入样式表的字体,而不列出也会加载它的图片。
注入的样式表里的 @import。 从 4.1.41 之后的版本开始,在 Chromium 目标上,构建会把 @import 的内容写进样式表,并放在它的 media、supports 或 layer 条件之下。Chrome 会丢弃注入样式表里的这条规则。这适用于通过 scripting.insertCSS 或 scripting.registerContentScripts 按文件注入的样式表,也适用于在 content_scripts 中声明的样式表。指向其他源的 import 保持原样,构建会给出带文件和行号的警告。
public/ 里被注入的样式表。 从 4.1.41 之后的版本开始,public/ 里的样式表会逐字节原样发布。如果它是按文件注入的,构建会为 Chrome 丢弃的 @import 警告一次。它还会为第一个被 Chrome 相对于被访问页面解析的 url() 警告一次,并建议使用 chrome-extension://__MSG_@@extension_id__/… 的写法。
被指明的文件发布在哪里。 从 4.1.41 之后的版本开始,直接传给 fetch 的路径会发布在读取它的脚本旁边,直接传给 chrome.runtime.getURL 的路径会发布在扩展根目录,保存在表或变量里的路径会在两个位置都发布。Chrome 从扩展根目录加载 devtools.panels.create 的页面路径和 sidePanel.setOptions 的路径。由动态导入的模块设置的图标,会发布在加载该模块的 worker 或页面旁边。
如果被引用的文件在你的项目中不存在,构建会给出一条指明缺失路径的警告,而不是让它在运行时静默失败。
推荐架构
让 background 入口保持精简,把功能逻辑放进共享模块。
把 background 上下文当作消息通信、存储访问和浏览器 API 调用的中心协调点。
从存储中恢复持久状态,不要假设 background 脚本始终运行。
使用 alarms、显式的事件监听器和小而专注的功能模块,而不是一条庞大的启动路径。
常见错误
把 service worker 当成永远运行的服务器进程。
把关键状态只保留在内存里。
在每次事件唤醒时都执行昂贵的启动工作。
把过多功能逻辑放在 popup 或 content script 代码中,而它们其实需要 background 级别的浏览器 API 访问。
最佳实践
MV3 优先的扩展应优先使用 background.service_worker。
让 background 入口文件保持小巧,把逻辑委派到共享模块。
避免在 service worker 中进行昂贵的启动工作;在安全的前提下延迟初始化。
在开发流程中把 manifest 中 background 字段的编辑视为结构性变更。
通过经过校验的消息处理器路由特权操作。
把持久设置和缓存放进浏览器存储,而不是只放在模块级变量里。
下一步