跳转到主要内容
Extension.js 从一个 manifest.json 出发,为 Chrome、Edge、Firefox 和 Safari 构建并运行浏览器扩展。它在所有扩展上下文中都能跑 TypeScript:background、content script、popup、options 和 sidebar。它默认使用 Rspack + SWC 管线。你不需要单独的 tsc 步骤、ts-loader,也不需要额外的打包器规则。 构建过程完全不需要 typescript 包。SWC 会编译你的源码并擦除类型。这个包只对编辑器工具和 tsc --noEmit 类型检查有意义。正因如此,缺少 typescript 包永远不会让构建失败,这一点和缺少框架集成包不同。

什么场景适合用 TypeScript

  • 你希望在各个扩展上下文中获得更安全的重构和更清晰的契约。
  • 你在 background script、content script 和 UI 界面之间共享逻辑。
  • 你需要在使用 AI 生成代码时让 API 的用法保持可预期。

模板示例

new-typescript

new-typescript template screenshot 适合搭建一个已配置好 TypeScript 默认设置的新标签页扩展。
仓库:extension-js/templates/newtab-typescript

content-typescript

content-typescript template screenshot 适合把 TypeScript 驱动的 content script 注入到现有页面。
仓库:extension-js/templates/content-typescript

自动生成的环境类型

对于 TypeScript 项目,Extension.js 会在项目根目录生成 extension-env.d.ts,里面包含环境声明(浏览器/运行时全局变量、EXTENSION_PUBLIC_* 环境变量以及打包器类型)。dev、build 和 start 都会重新生成它,所以编辑器的类型与 CI 中的 tsc --noEmit 始终保持一致。把它提交进版本库(或加进 git-ignore)都可以,下次运行时会重新创建。 从 4.1.39 之后的版本起,这个文件不存在时,只有在你的 tsconfig.json 会读到它的情况下才会被创建。见让 extension-env.d.ts 留在 include 列表里。

在现有扩展中使用

按下面的步骤把 TypeScript 添加到现有扩展。

安装

  1. 把 TypeScript 安装为开发依赖:
  1. 初始化 TypeScript 配置文件 tsconfig.json:

配置

TypeScript 检测和要求

Extension.js 会在 package.json 旁边查找 tsconfig.json。
  • 没有 tsconfig.json 的项目,只要构建会编译到 TypeScript,就会得到一份基线配置:manifest 指明的脚本、页面加载的脚本,或者它们通过相对路径导入的文件。构建会提示 Creating a default tsconfig.json 并继续。
  • 没有任何地方加载的 .ts 文件不算,单独声明 typescript 依赖也不算。从 4.1.41 之后的版本开始,构建不会往这样的项目里写入任何文件。
基线配置示例:
有两个默认值值得了解:
  • moduleResolution 为 bundler,它对应 Rspack + SWC 管线。已被移除的 node(node10)模式会让 TypeScript 7 上的 tsc --noEmit 失败。
  • 从 4.1.41 之后的版本起,moduleDetection 为 force,模板也这样设置。打包器把每个文件都当作模块,所以 tsc 也这样做。没有它时,不含 import 的脚本是全局脚本,顶层的 const status 会以 TS2451 失败,因为 DOM 类型中已经有 status。请把这一行加到旧的 tsconfig.json 中。
  • 只有当 Extension.js 在项目中检测到 JSX 框架时,jsx 才是 react-jsx。没有检测到时,它保持 preserve,也不会写入 jsxImportSource。从 4.1.20 起,框架项目还会得到 jsxImportSource,按检测到的框架设为 react、preact、vue 或 solid-js,这样 tsc --noEmit 解析的 JSX 运行时与构建一致。

自动类型

Extension.js 会在项目根目录生成 extension-env.d.ts。dev、build 和 start 每次都会重写它。该文件引用扩展 API、Extension.js 环境变量键和资源导入的类型声明。
extension-env.d.ts

扩展 API 的类型

Extension.js 用 chrome-types 为扩展 API 提供类型。这个包由 Chrome 从 Chromium 源码生成。browser 是原生命名空间,它的方法返回 Promise。chrome 是它的别名。这个包随 extension 一起安装,所以新项目不需要额外的类型包。
chrome-types 没有声明只有 Firefox 才有的 API。Firefox 的 browser.sidebarAction 和 browser.browserAction 由 Extension.js 自己提供类型。 从 4.1.40 之后的版本起,Extension.js 还在 chrome-types 之上补充了三项内容,让浏览器接受的代码能够通过类型检查:
  • 紧跟在你传入的参数之后的回调,例如 chrome.tabs.sendMessage(tabId, message, callback)。单独使用 chrome-types 时,回调只有放在所有可选参数之后才有类型。
  • Chrome 在运行时提供的枚举对象,例如 chrome.runtime.OnInstalledReason.INSTALL。这些是 Chrome 的对象。Firefox 提供的更少,部分键名也不同,所以面向两个浏览器的代码应当直接比较字符串,例如 reason === 'install'。
  • chrome.tabs.OnUpdatedInfo,也可以写作 chrome.tabs.TabChangeInfo,用于 tabs.onUpdated 的变更参数。
还有一个调用会报出 Chrome 并不会报的错误:new chrome.declarativeContent.ShowAction() 会提示缺少参数。请写成 new chrome.declarativeContent.ShowAction({}),Chrome 对两者的处理相同。

安装了 @types/chrome 的项目

安装了 @types/chrome 的项目会继续使用它。chrome 的类型来自这个包,browser 的类型和以前一样来自 webextension-polyfill。 @types/chrome 和 chrome-types 都声明了 chrome 全局变量,所以这两个包不能同时加载。生成的 extension-env.d.ts 只引用其中一个。当你的 package.json 列出了 @types/chrome 时,它引用 @types/chrome:
extension-env.d.ts
从 4.1.41 之后的版本起,node_modules 里有、但你的 package.json 没有列出的副本(例如提升到工作区根目录的副本),只对使用 TypeScript 5 或更早版本的项目生效。TypeScript 6 及更高版本不会加载项目没有引用的 @types 包,所以使用 TypeScript 6 或更高版本、又想用 @types/chrome 的工作区项目,要在自己的 package.json 里列出它。更早的版本只要项目目录或某个上级目录里存在 node_modules/@types/chrome,就会引用 @types/chrome。 改用 chrome-types:
  1. 从项目里移除 @types/chrome。
  2. 运行一次 extension dev 或 extension build。
回到 @types/chrome:
  1. 把 @types/chrome 安装为开发依赖。
  2. 运行一次 extension dev 或 extension build。

Polyfill 的类型

在默认配置下,browser 全局变量拥有来自 chrome-types 的原生类型。想要 webextension-polyfill 的类型,请导入这个模块:
这条导入只改变类型,以及你的代码所调用的对象。polyfill 何时运行,请阅读跨浏览器兼容性。

升级说明

更早的版本会随 extension 一起安装 @types/chrome,并用 webextension-polyfill 为 browser 提供类型。安装了 @types/chrome 的项目会保留这些类型。没有 @types/chrome 的项目在升级后会改用 chrome-types。 改用之后,tsc 可能会报告 chrome.tabs.TabChangeInfo 这样的名称不存在。安装 @types/chrome 可以保留以前的类型,然后运行一次 extension dev 或 extension build。

转译与类型检查

默认的打包管线会编译 TypeScript,但不会在打包时跑完整的 tsc 类型检查。 推荐的脚本:
tsc 不会写出 extension-env.d.ts。只有 dev、build 和 start 会重新生成它。在 CI 中,请先运行其中一条命令,再运行 tsc:

下一步

视频讲解