> ## 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` 會以 production 模式編譯你的擴充功能,並把輸出寫入 `dist/<browser>`。

針對 monorepo/submodule 專案,請參見 [環境變數](/docs/features/environment-variables#how-it-works) 中的設定階段環境變數解析(先尋找專案根目錄,再退回到 workspace 根目錄)。

## 何時使用 `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) 產生的同一份檔案),
  讓 CI 上的 `tsc --noEmit` 不論先前是否跑過 `dev` 都能順利通過。
  純 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`                               | 以逗號分隔的目標        |

## 引數與旗標

| 旗標                       | 別名              | 用途                                                              | 預設值             |
| ------------------------ | --------------- | --------------------------------------------------------------- | --------------- |
| `[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>`    | -               | 以逗號分隔的搭配擴充功能或 store URL。                                        | 未設              |
| `--install [boolean]`    | -               | 當缺少時安裝專案相依套件。                                                   | 依指令行為而定         |
| `--author`               | `--author-mode` | 啟用維護者診斷。                                                        | 停用              |

## 共用全域選項

也支援 [全域旗標](/docs/workflows/global-flags)。

## 模式覆寫

`--mode` 會覆寫此次建置的打包工具模式與 `NODE_ENV`。接受 `development`、`production` 或 `none`。當你需要在 staging 或除錯場景使用非正式版打包時,可用它對齊 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 為目標,將輸出壓縮成 zip,並儲存為 `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) 中了解設定的環境檔載入行為。
* 在 [可用的瀏覽器](/docs/browsers/browsers-available) 中查看支援的目標。