manifest.json、HTML 页面与特殊文件夹中收集脚本入口,并用基于 SWC(Speedy Web Compiler)的默认配置进行编译。
模板示例
javascript

content

JavaScript 能力
受支持的脚本入口
manifest.json 中的脚本声明示例
manifest.json 中的脚本声明示例:
开发期行为
- Content script: Extension.js 注入热模块替换(HMR)/重新挂载流程实现快速更新。
- 扩展页面: 页面脚本遵循页面 HMR 行为。
- Background/service worker: 取决于变更类型,脚本更新可能触发扩展硬重载。
- 入口列表变更: 当 manifest 的修改添加、移除或重命名了脚本入口时,正在运行的
extension dev会话会自行重启编译器并重新加载扩展。你不需要重启命令。从 4.1.41 之后的版本开始,脚本移到另一个 manifest 键时会话也会重启,例如把同一个文件从background.scripts移到background.service_worker。
脚本位置与约定
- 在项目根目录使用
scripts/存放以脚本为中心的扩展入口。 - 使用
pages/存放带有自身脚本的 HTML 入口。 - 保持 manifest 引用的路径稳定;在未更新 manifest 的情况下不要移动入口文件。
转换与打包默认设置
- 对 JS/TS/JSX/TSX,默认使用 SWC 作为转换器。
- Chromium 构建以
chrome >= 100为目标,或以 manifest 设置的minimum_chrome_version为目标。 - 从 4.2.0 之后的版本起,Firefox 构建以
firefox >= 98为目标,或以 manifest 设置的 Geckostrict_min_version的主版本为目标。更早的版本把没有strict_min_version的 Firefox 构建编译为chrome >= 100。 - 从 4.2.0 之后的版本起,Safari 构建以
safari >= 15.4为目标。它不从 manifest 读取版本,因为这个下限由 Xcode 项目持有。 - 生产构建的 CSS 压缩器使用与脚本相同的目标。
- Extension.js 使用浏览器优先的
package.json字段解析顺序(browser、module、main)。 - Extension.js 会以可预测方式输出入口,默认不会将代码拆分到多个输出文件中。
- 路径解析会重写受支持 API 中的静态扩展路径字面量。
动态 import 注意事项
- Content script 的动态 import 有运行时限制;Extension.js 会在可能时使用 loader 回退。
- 平台不允许在 service worker 里使用
import()或延后的importScripts。到 4.1.41 为止,Chromium service worker 里的懒加载导入会在运行时失败。从 4.1.41 之后的版本开始,构建会把它打包进 worker 文件,这个模块仍然只在第一次被导入时才运行。见懒加载。
最佳实践
- 让入口脚本保持精简,把功能逻辑放进共享模块。
- 对扩展 API 优先使用静态导入路径,便于路径解析安全地归一化它们。
- 避免在 content script 与 service worker 中使用不必要的动态 import。
- 在开发流程中把 manifest 中脚本列表的编辑视为结构性变更。
下一步
- 在 dev 更新行为 中了解更新结果。
- 在 特殊文件夹 中学习如何组织文件结构。
- 继续阅读 Background 脚本与 service worker。

