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

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 添加到现有扩展。安装
- 把 TypeScript 安装为开发依赖:
- 初始化 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的变更参数。
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
node_modules 里有、但你的 package.json 没有列出的副本(例如提升到工作区根目录的副本),只对使用 TypeScript 5 或更早版本的项目生效。TypeScript 6 及更高版本不会加载项目没有引用的 @types 包,所以使用 TypeScript 6 或更高版本、又想用 @types/chrome 的工作区项目,要在自己的 package.json 里列出它。更早的版本只要项目目录或某个上级目录里存在 node_modules/@types/chrome,就会引用 @types/chrome。
改用 chrome-types:
- 从项目里移除
@types/chrome。 - 运行一次
extension dev或extension build。
@types/chrome:
- 把
@types/chrome安装为开发依赖。 - 运行一次
extension dev或extension build。
Polyfill 的类型
在默认配置下,browser 全局变量拥有来自 chrome-types 的原生类型。想要 webextension-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:
下一步
- 了解 Extension.js 如何处理 ECMAScript 模块。
- 探索 Sass 模块等样式方案。
- 阅读浏览器扩展中的 JavaScript 和 TypeScript 文件。
- 对比各浏览器扩展框架对 TypeScript 的支持。

