跳转到主要内容
用一条 JavaScript/TypeScript 管线在 background、content script 和 UI 页面之间交付扩展行为。 Extension.js 从 manifest.json、HTML 页面与特殊文件夹中收集脚本入口,并用基于 SWC(Speedy Web Compiler)的默认配置进行编译。

模板示例

javascript

javascript template screenshot 带有 new-tab 页面的原生 JavaScript 扩展。
仓库:extension-js/templates/javascript

content

content template screenshot 注入到网页中的原生 JavaScript content script。
仓库:extension-js/templates/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 设置的 Gecko strict_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 中脚本列表的编辑视为结构性变更。

下一步