> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 浏览器扩展中的 JavaScript 与 TypeScript 文件

> 了解 .js、.ts、.tsx、manifest.json、background script 和 content script 在使用 Extension.js 构建的 Chrome、Firefox 和 Edge 扩展中是如何工作的。

浏览器扩展使用 JavaScript、TypeScript、HTML、CSS 以及一个 `manifest.json` 来定义行为、UI、权限和与浏览器的集成。本页介绍你在一个浏览器扩展项目中会见到的文件扩展名，以及它们各自归属在哪里。

如果你想了解的是作为 Chrome 或 Firefox 软件附加组件意义上的"扩展"，请从 [什么是浏览器扩展？](/docs/concepts/what-is-a-browser-extension) 开始。

## JavaScript 文件扩展名：`.js` 与 `.mjs`

浏览器扩展接受与 Web 平台其余部分相同的 JavaScript 文件扩展名：

| 文件扩展名  | 含义                                                   |
| ------ | ---------------------------------------------------- |
| `.js`  | 普通 JavaScript。根据加载方式被当作 ES 模块或经典脚本处理。                |
| `.mjs` | ES 模块。当你想强制使用模块语义时很有用，尤其是在 service worker 中。         |
| `.cjs` | CommonJS。在扩展源码中比较少见；偶尔会出现在 `extension.config.cjs` 中。 |

在 Manifest V3 中，当 `manifest.json` 在 `background` 块里包含 `"type": "module"` 时，背景 `service_worker` 会作为模块运行。详情见 [Manifest V3 排错](/docs/concepts/manifest-v3)。

## TypeScript 文件扩展名：`.ts` 与 `.tsx`

TypeScript 在 Extension.js 中作为一等源语言工作：

| 文件扩展名   | 含义                                |
| ------- | --------------------------------- |
| `.ts`   | 不含 JSX 的 TypeScript。              |
| `.tsx`  | 含 JSX 的 TypeScript（React、Preact）。 |
| `.d.ts` | 类型声明文件。不会被输出到构建产物。                |

你不需要从零写一个 `tsconfig.json`。Extension.js 自带合理的默认值。`chrome.*`、`browser.*`、`import.meta.env` 以及公共环境变量键的类型来自 `@types/chrome` 以及 Extension.js 自带的 ambient 类型。参见 [TypeScript](/docs/languages-and-frameworks/typescript)。

## React 文件扩展名：`.jsx` 与 `.tsx`

浏览器扩展中的 React 使用标准的 JSX 文件扩展名：

| 文件扩展名  | 含义                  |
| ------ | ------------------- |
| `.jsx` | 含 JSX 的 JavaScript。 |
| `.tsx` | 含 JSX 的 TypeScript。 |

React 既可以在扩展页面（popup、options、side panel、new-tab）中工作，也可以在注入到网页中的 content script 中工作。设置与 shadow DOM 模式见 [React](/docs/languages-and-frameworks/react)。

## 浏览器扩展文件：`manifest.json`、background、content scripts、pages

除了 JavaScript 和 TypeScript 源代码，一个浏览器扩展目录通常还会包含：

| 文件或目录           | 用途                                                  |
| --------------- | --------------------------------------------------- |
| `manifest.json` | 声明名称、版本、权限、入口点和元数据。                                 |
| 背景入口            | 长生命周期事件处理程序。Chromium 上的 Manifest V3 service worker。 |
| Content scripts | 注入到匹配某个 URL 模式的网页中的代码。                              |
| 扩展页面            | popup、options、side panel 或 new-tab HTML。            |
| 本地化文件           | `_locales/<lang>/messages.json` 翻译字符串。              |
| 图标与资源           | 工具栏图标、web-accessible resources、字体、图片。               |

Extension.js 将你的 `.ts`、`.tsx`、`.jsx`、`.vue`、`.svelte`、`.css`、`.less`、`.scss` 以及 `.module.*` 源代码编译成这种磁盘布局。它会按浏览器目标生成单独的目录（`dist/chrome`、`dist/firefox`、`dist/edge`）。

## Extension.js 如何编译 JavaScript 与 TypeScript 扩展

当你运行 `extension dev` 或 `extension build` 时，Extension.js 会：

1. 读取 `manifest.json` 并找出每一个入口点（background、content scripts、popup、options、side panel、new-tab、web-accessible HTML）。
2. 解析这些入口引用到的源文件，包括跨 `.ts`、`.tsx`、`.jsx`、`.vue`、`.svelte` 以及样式表类型的导入。
3. 用具备扩展感知能力的默认值通过 Rspack 编译：在有帮助的地方进行代码切分，在浏览器拒绝的地方（service worker、content script）不进行分块。
4. 把结果输出到 `dist/<browser>`，并附上为该目标过滤过的 manifest。

你用上面任意一种文件扩展名来写源代码。Extension.js 会处理打包、polyfill、保存即重载循环以及按浏览器的打包。

## 下一步

* 试用 [`extension create`](/docs/commands/create) 来脚手架生成一个 TypeScript 或 React 扩展。
* 阅读 [TypeScript](/docs/languages-and-frameworks/typescript) 与 [React](/docs/languages-and-frameworks/react)。
* 阅读 [Manifest V3 排错](/docs/concepts/manifest-v3) 了解 service worker 与模块规则。
* 使用 [`extension build`](/docs/commands/build) 构建。