manifest.json 编译 content script 入口,并为运行时挂载与热模块替换(HMR)行为包装它们,生成可预测的 content_scripts/* 产物。
Content script 能力
模板示例
content

content-react

支持的 manifest 字段
Content script 声明示例
manifest.json 中的 content script 声明示例:
编写契约
对每一个类 content script 入口,Extension.js 期望一个挂载风格的默认导出。这是一个函数,用来设置行为,可选地返回一个清理回调:- 模块应该
export default一个同步函数。 - 该函数应执行设置工作。
- 它可以返回一个同步的清理回调。
- Extension.js 不支持以类作为默认导出。
- 被
manifest.json > content_scripts[*].js引用的文件。 - 你放在项目
scripts/文件夹中并用作脚本入口的文件。
合法的形式
不合法的形式
异步 content script 的建议
即使功能内部要做异步工作,默认导出也应保持同步。在函数内部开始异步工作,并返回一个同步的清理函数。 为什么重要:在开发期间,Extension.js 会重新挂载 content script。如果没有清理函数,你可能会复制出多个 UI、事件监听器、观察者和定时器。违反契约时会发生什么
- 没有默认导出:Extension.js 在开发期发出警告并跳过挂载。
- 默认导出不是函数:Extension.js 在开发期发出警告并跳过挂载。
- 默认导出返回了 Promise:模块仍然运行,但 Extension.js 不会把那个
Promise当作清理函数。
整个扩展重载后什么会留下
当extension dev 中的一次修改触发整个扩展重载时,保持打开的标签页里仍然留着重载之前的那份 content script 副本。这个旧副本的去向取决于浏览器引擎:
- Chromium 会让旧副本在打开的标签页里和新副本一起继续运行,定时器和监听器也包括在内,直到标签页重新加载为止。它的
chrome.runtime.id已经不存在,也不会为它调用任何清理,即使脚本的默认导出返回了清理函数也一样。 - Firefox 会丢弃旧副本。不会为它调用任何清理,它也不会再运行。
chrome.runtime.id 消失后停下来:
data-extension-root 的宿主元素之下。下一个副本启动时,Extension.js 会移除旧副本遗留的这些宿主,在 Chromium 和 Firefox 上都是如此:
运行时 wrapper 行为
- Extension.js 用挂载/运行时辅助逻辑包装 content script 模块。
- wrapper 在生产构建中同样生效,没有选项可以关闭它。
- 从 4.1.41 之后的版本起,wrapper 在你自己的 loader 之后运行。见 Loader 顺序。
- 在开发模式下,Extension.js 会添加 HMR 的 accept/dispose 行为和重新挂载流程。
- 在开发期,CSS 更新会触发重新挂载事件(
__EXTENSIONJS_CSS_UPDATE__)。 - Extension.js 会遵循 manifest 中的
run_at时机。
多入口 content script
你可以在同一份 manifest 中声明多个 content script 入口。每个入口都使用自己的匹配模式、运行时机和 world 设置独立编译。content-multi-one-entry

content_scripts manifest 入口下。
content-multi-three-entries

content_scripts manifest 入口,分别使用各自的匹配模式。
传统的多文件入口
当一个content_scripts.js 数组列出多个既没有 import 也没有 export 的普通 JavaScript 文件时,Extension.js 会把它们拼接成一个 bundle。把每个文件当作独立模块打包会破坏它们。浏览器会按顺序把这些经典文件注入到同一个共享作用域中,拼接正是为了保持这一点:
- 跨文件的隐式全局变量仍然有效。第一个文件中的顶层
var或函数对下一个文件依然可见。 - 每个源文件都会注册为构建依赖,因此保存这一组中的任意文件都会触发重新构建。
- 输出的 source map 指向你真实的文件与行号,因此错误可以追溯回原始代码。
- 拼接组中的原始
.ts文件会在拼接之前用内置的 SWC 剥离类型。
import 或 export 的入口保持常规的模块打包方式。
scripts/ 文件夹的行为
scripts/ 文件夹用于没有任何 HTML 页面入口声明的脚本入口。实际上,这些入口遵循与 content script 相同的默认导出模式。
也就是说,scripts/ 并不是一个用来放置零散 JavaScript 文件的通用文件夹:
- 当脚本入口文件挂载行为时,仍然应该默认导出一个函数。
- 在监听模式下,Extension.js 会把
scripts/下受支持文件的新增或删除视为结构性变更。 - 当 manifest 的修改添加、移除或重命名了脚本入口时,正在运行的
extension dev会话会自行重启编译器并重新加载扩展。你不需要重启命令。从 4.1.41 之后的版本开始,脚本移到另一个 manifest 键时会话也会重启,例如把同一个文件从background.scripts移到background.service_worker。
输出路径
Extension.js 按 manifest 入口的索引归一化 content script 产物:content-0.abcd1234.js)。这会迫使浏览器在每次重新构建后加载一个全新的 chrome-extension:// URL。
Chrome 会激进地缓存扩展资源,因此该哈希可以避免读取到过时代码。生产构建则使用干净的 content-0.js 名称。
MAIN world 注意事项
content-main-world
通过一个能直接把 UI 注入到页面上下文的可用示例,体验 MAIN world content script:
world: "MAIN"在 Chrome 111、Firefox 128 和 Safari 18 及更高版本上可用。 在这三种浏览器上,脚本都运行在页面自己的 JavaScript world 中。在 Firefox 上,Manifest V2 与 Manifest V3 都是如此。- MAIN world 脚本没有扩展 API。
chrome.runtime、chrome.storage等在那里都不可用,你只能访问页面上下文中的全局对象。请给它配一个 isolated world 脚本来与扩展通信。 - 只有面向更旧的浏览器时才值得用浏览器前缀。 只有在必须支持早于上述版本的浏览器时,才使用
chromium:world并配一个 isolated world 回退。 scripts/文件也可以运行在 MAIN world 中。 在运行时用world: "MAIN"注册或注入它。参见在运行时注入脚本。- 从 4.2.0 起,编译失败的 MAIN world 脚本不会发布损坏的产物。
- 把 MAIN world 当作高级路径对待。尽早在每个目标浏览器上验证行为。
isolated world 桥接
MAIN world 脚本无法调用扩展 API,因此 Extension.js 会为每个 MAIN 组配一个可以调用的辅助脚本。请预期构建后的 manifest 在这里与你的源文件不同:- dist 中的 manifest 比源文件包含更多的
content_scripts入口。Extension.js 会在每个 MAIN 组之前插入一条 isolated world 桥接入口。 - 桥接入口的资源索引排在你自己的入口之后。你的
content_scripts/content-N产物保留生成它们的源入口的索引。 - 桥接通过
runtime.getURL解析扩展 URL,并把 MAIN world 的脚本 chunk 注入页面。从 4.1.39 之后的版本起,它在 Firefox 上不再注入任何东西,MAIN world 脚本自己加载它的 chunk。 - 桥接在处理消息前会校验
event.source是否为同一个 window。 - 它只会注入扩展协议的 URL(
chrome-extension://、moz-extension://)或相对路径,绝不会注入任意的远程 URL。
在 Firefox 上页面能读到的扩展 URL
在 Firefox 上,你的moz-extension:// 源带有一个每次安装都不同的 id。页面一旦拿到它,就能再次认出同一个浏览器。
从 4.1.39 之后的版本起,构建把这个源交给 MAIN world 脚本时,不会把它写进页面的 DOM。页面无法从这次交接中读到这个源。
这只覆盖构建自己的内部通道。你的脚本放进 DOM 的任何东西,页面都读得到:
- 指向扩展资源的
<img src>或<link href>。 - 对扩展 URL 的
fetch,前提是页面已经改写了fetch。 - 组件的
<style>块,其中的url()指向扩展资源。这份样式表会落在 document 里的一个<style>元素中。
Isolated vs MAIN 快速示例
MAIN,并考虑扩展 API 与运行时方面的限制。
用前缀支持更旧的浏览器
在 Chrome 111、Firefox 128 和 Safari 18 及更高版本上,上面快速示例里不带前缀的world 键就足够了。早于 128 的 Firefox 会忽略 world 键,并在 isolated world 中运行脚本。如果你必须支持这样的版本,使用 浏览器特定前缀 仅为 Chromium 声明 MAIN world,并为 Firefox 提供 isolated 回退。这样一来,每个 Firefox 版本都会运行回退脚本,包括那些支持 MAIN 的版本:
chromium: 前缀的字段,因此第二条入口到达 Firefox 构建时既没有 js 也没有 css。Firefox 从它那里什么也得不到。构建会把这条入口从 Firefox manifest 中去掉,并打印原因:
js。带前缀的键会覆盖同名的普通键,因此 Chromium 仍然在 MAIN world 中使用 chromium:js,而 Firefox 在 isolated world 中运行普通的 js。这样一条入口就能同时覆盖两种浏览器,构建也不会打印警告:
js 是每个目标都会读取的基础键,所以在任何不解析 chromium: 的浏览器上,这条入口都保持完整。firefox:js 也能保留这条入口,但只在 Gecko 目标上生效,而前缀页面的规则是:以普通键为基础,只给例外加前缀。
匹配与执行建议
浏览器仍然控制 content script 在哪里运行。Extension.js 只负责打包文件,manifest 入口仍然决定脚本运行的时机与位置。- 让
matches尽量收窄到该功能确实需要的范围。 - 只有在功能确实需要时才添加
exclude_matches、all_frames或match_about_blank。 - 把
run_at与world视为功能契约的一部分,而不是实现细节。 - 当 content script 的运行位置发生变化时,重新测试权限和主机权限的作用范围。
开发期行为
- 编辑 content script 代码通常会通过 wrapper 驱动的 HMR/重新挂载流程更新。
- 仅 CSS 的入口会获得开发辅助行为,让样式更新可以传播。
- 当 manifest 的修改添加、移除或重命名了脚本入口时,正在运行的
extension dev会话会自行重启编译器并重新加载扩展。你不需要重启命令。从 4.1.41 之后的版本开始,脚本移到另一个 manifest 键时会话也会重启,例如把同一个文件从background.scripts移到background.service_worker。
最佳实践
- 让 content script 入口文件保持精简,把逻辑委派到共享模块。
- 仔细限定选择器/样式范围,避免与宿主页面冲突。
- 当行为依赖时机/上下文时,优先显式设置
run_at和world。 - 在开发流程中把 manifest 中 content script 列表的变更视为结构性变更。
- 通过经过校验的消息通信传递页面派生的数据,而不是直接在 content script 中执行特权工作。
- 默认使用 isolated world,只有在确实需要页面上下文时才切换到
MAIN。
下一步
- 在 dev 更新行为 中了解更新结果。
- 用 消息通信 设计跨上下文通信。
- 在 权限与主机权限 中评估访问范围。
- 了解 web-accessible 资源。
- 继续阅读 开发中的 locales。

