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

# 為 Chrome、Edge 與 Firefox 進行多平台建置

> 用同一份程式碼為 Chrome、Edge 與 Firefox 建置與封裝擴充功能，不需分別的建置腳本。輸出至 dist 並產生 zip。

用同一份擴充功能為多個瀏覽器建置與封裝，輸出可預期。

把同一份擴充功能上架到 Chrome、Edge 與 Firefox，不需要維護分別的建置腳本。Extension.js 會為每個目標執行正式建置，將產物寫入 `dist/<browser>`，也能為發佈產生 zip 封裝。

## 運作方式

執行正式建置：

<CodeGroup>
  ```bash npm theme={null}
  npx extension build
  ```

  ```bash pnpm theme={null}
  pnpx extension build
  ```

  ```bash yarn theme={null}
  yarn dlx extension build
  ```

  ```bash bun theme={null}
  bunx extension build
  ```

  ```bash bun theme={null}
  bunx extension build
  ```
</CodeGroup>

預設的瀏覽器目標是 `chromium`，除非你覆寫它。

## 瀏覽器選擇

你可以鎖定特定的瀏覽器／引擎：

<CodeGroup>
  ```bash npm theme={null}
  npx extension build --browser=chrome
  ```

  ```bash pnpm theme={null}
  pnpx extension build --browser=chrome
  ```

  ```bash yarn theme={null}
  yarn dlx extension build --browser=chrome
  ```

  ```bash bun theme={null}
  bunx extension build --browser=chrome
  ```

  ```bash bun theme={null}
  bunx extension build --browser=chrome
  ```
</CodeGroup>

<CodeGroup>
  ```bash npm theme={null}
  npx extension build --browser=firefox
  ```

  ```bash pnpm theme={null}
  pnpx extension build --browser=firefox
  ```

  ```bash yarn theme={null}
  yarn dlx extension build --browser=firefox
  ```

  ```bash bun theme={null}
  bunx extension build --browser=firefox
  ```

  ```bash bun theme={null}
  bunx extension build --browser=firefox
  ```
</CodeGroup>

支援的值包括：

* `chrome`
* `edge`
* `firefox`
* `chromium`
* `chromium-based`
* `gecko-based` / `firefox-based`（別名）

你也可以在一條指令中執行建置矩陣：

<CodeGroup>
  ```bash npm theme={null}
  npx extension build --browser=chrome,edge,firefox
  ```

  ```bash pnpm theme={null}
  pnpx extension build --browser=chrome,edge,firefox
  ```

  ```bash yarn theme={null}
  yarn dlx extension build --browser=chrome,edge,firefox
  ```

  ```bash bun theme={null}
  bunx extension build --browser=chrome,edge,firefox
  ```

  ```bash bun theme={null}
  bunx extension build --browser=chrome,edge,firefox
  ```
</CodeGroup>

這會依序為 `chrome`、`edge` 與 `firefox` 進行建置。

## 輸出結構

每個目標會寫入自己的資料夾：

* `dist/chrome`
* `dist/edge`
* `dist/firefox`
* `dist/chromium`
* `dist/chromium-based`
* `dist/gecko-based`

### 建置能力

| 選項                      | 作用                                        |
| ----------------------- | ----------------------------------------- |
| `--browser=<target>`    | 為特定瀏覽器或引擎家族建置。                            |
| `--zip`                 | 為每個目標輸出產生發佈用 zip。                         |
| `--zip-filename=<name>` | 覆寫預設的 zip 檔名。                             |
| `--zip-source`          | 額外建立原始碼封存檔。                               |
| `--polyfill`            | 在 Chromium 家族目標啟用 `browser.*` API 的相容性行為。 |

## 產生 zip 檔

用 `--zip` 為每個目標輸出產生發佈 zip：

<CodeGroup>
  ```bash npm theme={null}
  npx extension build --zip
  ```

  ```bash pnpm theme={null}
  pnpx extension build --zip
  ```

  ```bash yarn theme={null}
  yarn dlx extension build --zip
  ```

  ```bash bun theme={null}
  bunx extension build --zip
  ```

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

預設 zip 名稱會使用清理後的 manifest `name` + `version`，例如：

* `my-extension-1.0.0.zip`

自訂檔名：

<CodeGroup>
  ```bash npm theme={null}
  npx extension build --zip --zip-filename=my-release
  ```

  ```bash pnpm theme={null}
  pnpx extension build --zip --zip-filename=my-release
  ```

  ```bash yarn theme={null}
  yarn dlx extension build --zip --zip-filename=my-release
  ```

  ```bash bun theme={null}
  bunx extension build --zip --zip-filename=my-release
  ```

  ```bash bun theme={null}
  bunx extension build --zip --zip-filename=my-release
  ```
</CodeGroup>

這會在目標 `dist/<browser>` 資料夾內建立 `my-release.zip`。

## 包含原始碼封存檔

使用 `--zip-source` 在發佈輸出旁邊另外產生原始碼封存檔。

`--zip-source` 會產生：

* `dist/<name>-<version>-source.zip`

## Polyfill 瀏覽器 API

如果你的程式碼依賴 Gecko 風格的 `browser.*` API，又需要 Chromium 相容性，可以啟用 `--polyfill`：

<CodeGroup>
  ```bash npm theme={null}
  npx extension build --polyfill
  ```

  ```bash pnpm theme={null}
  pnpx extension build --polyfill
  ```

  ```bash yarn theme={null}
  yarn dlx extension build --polyfill
  ```

  ```bash bun theme={null}
  bunx extension build --polyfill
  ```

  ```bash bun theme={null}
  bunx extension build --polyfill
  ```
</CodeGroup>

## 最佳實務

* **在持續整合（CI）中為每個目標分別建置**：把每個瀏覽器輸出視為獨立產物。
* **使用瀏覽器矩陣指令做一致性檢查**：在同一個流水線步驟內及早抓到目標專屬問題。
* **有意識地進行封裝**：用 `--zip` 上架到應用商店，用 `--zip-source` 產生可追溯的原始碼產物。
* **保留明確的目標設定**：用 `extension.config.*` 的指令／瀏覽器預設值來確保建置可重現。

## 下一步

* 進一步了解 [可用的瀏覽器](/docs/browsers/browsers-available)。
* 深入了解 [路徑解析](/docs/features/path-resolution) 來掌握資產／輸出對應的細節。