> ## 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.

# 用 build 命令产出生产环境扩展产物

> 用 Extension.js 的 build 命令为 Chrome、Edge 或 Firefox 生成生产环境扩展产物。支持多浏览器与 zip 输出。

为一个或多个浏览器目标生成生产环境扩展产物。

`build` 会以生产模式编译你的扩展，并将输出写入 `dist/<browser>`。

对于 monorepo / 子模块项目，关于配置期的环境变量解析（优先项目根，再退回工作区根），请参见 [环境变量](/docs/features/environment-variables#how-it-works)。

## 什么时候使用 `build`

* 为 Chrome Web Store、Edge Add-ons 或 Firefox Add-ons 准备扩展包。
* 在持续集成（CI）中跑出可复现的生产产物。
* 在提交前验证生产打包的输出以及各浏览器目标之间的差异。

## build 命令的能力

| 能力        | 你得到什么                   |
| --------- | ----------------------- |
| 生产编译      | 为每个目标产出优化过的扩展产物         |
| 多目标输出     | 一条命令构建多个浏览器目标           |
| 打包支持      | 创建分发用的 zip 产物，可选地附带源代码包 |
| 适合 CI 的行为 | 在自动化中保持构建输出与命名可预期       |

## 用法

<CodeGroup>
  ```bash npm theme={null}
  extension build [project-path] [options]
  ```

  ```bash pnpm theme={null}
  extension build [project-path] [options]
  ```

  ```bash yarn theme={null}
  extension build [project-path] [options]
  ```

  ```bash bun theme={null}
  extension build [project-path] [options]
  ```

  ```bash bun theme={null}
  extension build [project-path] [options]
  ```
</CodeGroup>

## build 输出

运行 `build` 后，Extension.js 会为所选浏览器目标生成优化过的文件。输出位于 `dist/`，每个目标一个子目录。每个目录都包含打包后的 JavaScript、CSS、HTML 和必要的运行时资源。

<Note>
  对于 TypeScript 项目，`build` 也会重新生成 `extension-env.d.ts`
  环境类型声明（与 [`dev`](/docs/commands/dev) 写出的是同一个文件），
  所以无论你之前是否运行过 `dev`，CI 上的 `tsc --noEmit` 都能保持干净。
  纯 JavaScript 项目会跳过这一步。
</Note>

**输出结构示例：**

```plaintext theme={null}
dist/
├── chrome/
│   ├── manifest.json
│   ├── background/service_worker.js
│   ├── content_scripts/content-0.js
├── edge/
│   ├── manifest.json
│   ├── background/service_worker.js
│   ├── content_scripts/content-0.js
```

## 浏览器目标矩阵

| 目标类型 | 示例                                             | 说明             |
| ---- | ---------------------------------------------- | -------------- |
| 具名目标 | `chromium`、`chrome`、`edge`、`firefox`           | 构建某一个特定的浏览器目标  |
| 引擎目标 | `chromium-based`、`gecko-based`、`firefox-based` | 适合以引擎家族为单位的工作流 |
| 多目标  | `chrome,firefox`                               | 用逗号分隔的多个目标     |

## 参数与 flag

| flag                     | 别名              | 作用                                                              | 默认值             |
| ------------------------ | --------------- | --------------------------------------------------------------- | --------------- |
| `[path]`                 | -               | 构建一个本地扩展项目。                                                     | `process.cwd()` |
| `--browser <browser>`    | -               | 浏览器 / 引擎目标（`chromium`、`chrome`、`edge`、`firefox`、引擎别名或逗号分隔的多个值）。 | `chromium`      |
| `--polyfill [boolean]`   | -               | 为 Chromium 目标启用 `browser.*` API 兼容 polyfill。                    | `false`         |
| `--zip [boolean]`        | -               | 创建打包好的 zip 产物。                                                  | `false`         |
| `--zip-source [boolean]` | -               | 在 zip 输出中包含源代码文件。                                               | `false`         |
| `--zip-filename <name>`  | -               | 设置自定义的 zip 文件名。                                                 | 扩展名 + 版本号       |
| `--silent [boolean]`     | -               | 抑制构建日志。                                                         | `false`         |
| `--mode <mode>`          | -               | 覆盖打包器的模式（`development`、`production` 或 `none`）。同时会设置 `NODE_ENV`。 | `production`    |
| `--extensions <list>`    | -               | 用逗号分隔的协同扩展或商店 URL。                                              | 未设置             |
| `--install [boolean]`    | -               | 缺失依赖时安装项目依赖。                                                    | 按命令默认行为         |
| `--author`               | `--author-mode` | 启用维护者诊断信息。                                                      | 关闭              |

## 共享的全局选项

也支持 [全局 flag](/docs/workflows/global-flags)。

## 模式覆盖

`--mode` 会覆盖构建的打包器模式以及 `NODE_ENV`。可选值为 `development`、`production` 或 `none`。当你需要为 staging 或调试产出非生产 bundle 时（类似 Vite / webpack 的工作流），可以用它来对齐行为。

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash bun theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash bun theme={null}
  extension build ./my-extension --mode development
  ```
</CodeGroup>

无效的值会以错误退出；默认值仍然是 `production`。

## zip 行为

| 选项               | 作用            | 典型用途        |
| ---------------- | ------------- | ----------- |
| `--zip`          | 创建打包产物的 zip   | 商店提交 / 手动分发 |
| `--zip-filename` | 设置自定义 zip 名称  | CI 命名规范     |
| `--zip-source`   | 在产物旁额外加上源代码归档 | 合规 / 审核流水线  |

## 示例

### 带 zip 输出与自定义文件名的构建

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash bun theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash bun theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```
</CodeGroup>

在这个示例中，构建以 Edge 与 Chrome 为目标，对输出进行打包，并保存为 `my-extension.zip`。

### 带 polyfill 支持的构建

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash bun theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash bun theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```
</CodeGroup>

在这个示例中，构建以 Chrome 与 Firefox 为目标，并在相关地方加入 polyfill 支持。

### 构建源代码与产物 zip

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash bun theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash bun theme={null}
  extension build ./my-extension --zip --zip-source
  ```
</CodeGroup>

## 最佳实践

* **查看构建日志：** 每次构建后检查日志，看是否有警告与缺失资源。
* **优化你的 manifest：** 让 `manifest.json` 与每个目标浏览器都兼容。
* **有意识地命名产物：** 用 `--zip-filename` 让 CI 产物命名保持稳定。
* **逐个目标验证输出：** 发布前检查每一个 `dist/<browser>` 目录。

## 下一步

* 用 [`preview`](/docs/commands/preview) 运行已有的构建产物。
* 用 [`start`](/docs/commands/start) 一条命令构建并启动。
* 在 [`extension.config.js`](/docs/features/extension-configuration) 中集中配置共享默认值。
* 在 [环境变量](/docs/features/environment-variables#how-it-works) 中查看配置期的 env 加载行为。
* 在 [可用浏览器](/docs/browsers/browsers-available) 中查看支持的目标。