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

# Extension 設定（extension.config.js）

> 在單一設定檔中設定瀏覽器預設值、指令行為與 Rspack bundler 選項，套用於 dev、start、preview 與 build 指令。

用一份設定檔同時設定瀏覽器預設值、指令行為與 bundler 客製化。

跨團隊共用瀏覽器預設、指令選項與建置設定，不再重複輸入 CLI 旗標。Extension.js 會從專案根目錄讀取 `extension.config.js`（或 `.mjs` / `.cjs`），並套用到每個指令與 bundler。

## 運作方式

在專案根目錄（通常和 `package.json` 同層）加上 `extension.config.js`。

支援的檔名：

* `extension.config.js`
* `extension.config.mjs`
* `extension.config.cjs`

頂層的鍵：

| 鍵                   | 說明                                        |
| ------------------- | ----------------------------------------- |
| `browser`           | 依瀏覽器目標分鍵的瀏覽器專屬預設值。                        |
| `commands`          | 各指令的預設值（`dev`、`start`、`preview`、`build`）。 |
| `extensions`        | 跨指令套用的附屬擴充功能（僅載入）。                        |
| `transpilePackages` | 打包前要先編譯的套件（在 monorepo／workspace 設定中很實用）。  |
| `config`            | 用來擴充／覆寫產生出的 Rspack 設定的 hook。              |

### 設定檔的環境載入

`extension.config.*` 在 Node 中執行，應該從 `process.env.*` 讀取值。

* Extension.js 在評估 `extension.config.*` 之前，會預先載入 env 檔。
* 它會先檢查專案資料夾。
* 在 monorepo 中，若 Extension.js 找不到專案本地的 `.env*`，會 fallback 到最近的 workspace 根目錄，也就是包含 `pnpm-workspace.yaml` 的資料夾。
* 比起在設定檔中匯入 `dotenv`，建議優先使用內建的 env 預載。

### 瀏覽器設定

需要為每個目標設定不同的瀏覽器預設值？使用 `browser`：

```js theme={null}
export default {
  browser: {
    chrome: {
      profile: "path/to/profile",
      preferences: { darkMode: true },
      browserFlags: ["--disable-web-security"],
      excludeBrowserFlags: ["--mute-audio"],
    },
    "chromium-based": {
      chromiumBinary: "/path/to/brave-or-other-chromium-binary",
    },
    firefox: {
      geckoBinary: "/path/to/firefox",
    },
  },
};
```

支援的瀏覽器鍵包括：`chrome`、`edge`、`firefox`、`chromium`、`chromium-based`、`gecko-based`、`firefox-based`。

常用的瀏覽器欄位：

* `profile`、`persistProfile`
* `preferences`
* `browserFlags`、`excludeBrowserFlags`
* `chromiumBinary`、`geckoBinary`
* `extensions`（僅載入的附屬擴充功能）

#### 瀏覽器目標能力

| 鍵                     | 作用                           |
| --------------------- | ---------------------------- |
| `profile`             | 設定瀏覽器啟動時使用的 profile 路徑（或行為）。 |
| `persistProfile`      | 在多次執行間沿用 profile 資料。         |
| `preferences`         | 套用瀏覽器偏好設定覆寫。                 |
| `browserFlags`        | 在瀏覽器程序啟動時加入旗標。               |
| `excludeBrowserFlags` | 移除不想使用的預設啟動旗標。               |
| `chromiumBinary`      | 使用自訂的 Chromium 系二進位檔路徑。      |
| `geckoBinary`         | 使用自訂的 Gecko/Firefox 二進位檔路徑。  |
| `extensions`          | 與主擴充功能一起載入附屬擴充功能。            |

### 指令設定

用 `commands` 定義每個指令的預設值：

```js theme={null}
export default {
  transpilePackages: ["@workspace/ui"],
  commands: {
    dev: {
      browser: "chrome",
      polyfill: true,
      logLevel: "info",
      persistProfile: true,
      browserFlags: ["--headless=new"],
      extensions: { dir: "./extensions" },
    },
    start: {
      browser: "firefox",
      source: "https://example.com",
    },
    preview: {
      browser: "edge",
      noBrowser: false,
    },
    build: {
      browser: "chrome",
      zip: true,
      zipSource: true,
      zipFilename: "my-extension.zip",
      transpilePackages: ["@workspace/ui", "@workspace/icons"],
    },
  },
};
```

注意事項：

* Extension.js 會把頂層的 `extensions` 與 `transpilePackages` 合併進各指令的預設值。
* 各指令的值會覆寫頂層的值。
* `start` 指令會在內部依序執行 `build` 與 `preview`。Extension.js 會套用 `commands.start` 中的設定，包括 `profile`、`browserFlags` 與 `startingUrl` 等瀏覽器啟動選項。你也可以把建置專屬的設定放在 `commands.build`。

#### 指令共用能力

| 鍵                     | 適用於                             | 作用                                           |
| --------------------- | ------------------------------- | -------------------------------------------- |
| `browser`             | `dev`、`start`、`preview`、`build` | 設定瀏覽器或瀏覽器家族目標。                               |
| `profile`             | `dev`、`start`、`preview`         | 設定瀏覽器 profile 路徑／行為。                         |
| `persistProfile`      | `dev`、`start`、`preview`         | 在多次執行間沿用瀏覽器 profile 資料。                      |
| `chromiumBinary`      | `dev`、`start`、`preview`         | 使用自訂的 Chromium 系二進位檔。                        |
| `geckoBinary`         | `dev`、`start`、`preview`         | 使用自訂的 Gecko 系二進位檔。                           |
| `polyfill`            | `dev`、`start`、`build`           | 在相關情境啟用相容性 polyfill 行為。                      |
| `preferences`         | `dev`、`start`、`preview`         | 套用瀏覽器偏好設定覆寫。                                 |
| `browserFlags`        | `dev`、`start`、`preview`         | 在瀏覽器程序啟動時加入旗標。                               |
| `excludeBrowserFlags` | `dev`、`start`、`preview`         | 移除不想使用的預設啟動旗標。                               |
| `startingUrl`         | `dev`、`start`、`preview`         | 在瀏覽器啟動時開啟指定 URL。                             |
| `port`                | `dev`、`start`、`preview`         | 設定 runner／DevTools 連接埠。                      |
| `host`                | `dev`、`start`、`preview`         | 設定開發伺服器主機。Docker／dev container 請用 `0.0.0.0`。 |
| `noBrowser`           | `dev`、`start`、`preview`         | 停用瀏覽器啟動。                                     |
| `extensions`          | `dev`、`start`、`preview`、`build` | 載入附屬擴充功能（或擴充功能清單）。                           |
| `install`             | `dev`、`start`、`build`           | 執行前先安裝缺少的依賴項。                                |
| `transpilePackages`   | `dev`、`start`、`preview`、`build` | 編譯指定的 workspace／外部套件。                        |

#### `build` 指令能力

| 鍵             | 作用                          |
| ------------- | --------------------------- |
| `zip`         | 產生封裝後的 zip 產物。              |
| `zipSource`   | 為審查／合規流程額外產出原始碼 bundle／封存檔。 |
| `zipFilename` | 設定自訂的 zip 輸出檔名。             |
| `silent`      | 減少建置記錄輸出。                   |

#### `dev` 指令能力

| 鍵                     | 作用                                   |
| --------------------- | ------------------------------------ |
| `noOpen`              | 啟動開發伺服器但不自動開啟瀏覽器。                    |
| `source`              | 從遠端來源 URL 啟用原始碼檢查流程。                 |
| `watchSource`         | 當監看的更新發生時，重新執行原始碼檢查。                 |
| `sourceFormat`        | 設定原始碼輸出格式（`pretty`、`json`、`ndjson`）。 |
| `sourceSummary`       | 輸出精簡的原始碼摘要。                          |
| `sourceMeta`          | 在原始碼輸出中包含頁面中繼資料。                     |
| `sourceProbe`         | 用特定 CSS 選擇器探查原始碼輸出。                  |
| `sourceTree`          | 控制精簡的擴充功能樹狀輸出。                       |
| `sourceConsole`       | 在原始碼輸出中包含 console 摘要。                |
| `sourceDom`           | 在原始碼輸出中包含 DOM 快照／差異。                 |
| `sourceMaxBytes`      | 限制原始碼輸出 payload 的大小。                 |
| `sourceRedact`        | 控制原始碼遮蔽策略。                           |
| `sourceIncludeShadow` | 控制 Shadow DOM 的包含策略。                 |
| `sourceDiff`          | 在原始碼監看更新時包含 diff 中繼資料。               |

#### 記錄能力

| 鍵            | 適用於                     | 作用                                 |
| ------------ | ----------------------- | ---------------------------------- |
| `logs`       | `dev`、`start`、`preview` | 設定最低記錄等級（`off` 到 `all`）。           |
| `logContext` | `dev`、`start`、`preview` | 依情境過濾記錄（`background`、`content` 等）。 |
| `logFormat`  | `dev`、`start`、`preview` | 設定輸出格式（`pretty`、`json`、`ndjson`）。  |
| `logUrl`     | `dev`、`start`、`preview` | 依 URL 模式過濾記錄。                      |
| `logTab`     | `dev`、`start`、`preview` | 依分頁 ID 過濾記錄。                       |

### Rspack 設定

需要進階的 bundler 客製化？使用 `config` 來修補產生出的 Rspack 設定：

```js theme={null}
export default {
  config: (config) => {
    config.module.rules.push({
      test: /\.mdx$/,
      use: ["babel-loader", "@mdx-js/loader"],
    });
    return config;
  },
};
```

`config` 也可以是物件，Extension.js 會把它合併到產生出的設定之上。

## 完整範例

```js theme={null}
export default {
  browser: {
    chrome: { browser: "chrome", profile: "default" },
    firefox: { browser: "firefox", persistProfile: true },
    "chromium-based": {
      browser: "chromium-based",
      chromiumBinary:
        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    },
  },
  commands: {
    dev: {
      browser: "chrome",
      polyfill: true,
      host: "0.0.0.0",
      extensions: { dir: "./extensions" },
    },
    start: { browser: "edge" },
    preview: { browser: "firefox" },
    build: {
      zipFilename: "extension.zip",
      zip: true,
      zipSource: true,
    },
  },
  extensions: { dir: "./extensions" },
  transpilePackages: ["@workspace/ui"],
  config: (config) => config,
};
```

## 最佳實務

* **瀏覽器專屬值放在 `browser`**：讓指令定義專注於工作流程，而非瀏覽器內部細節。
* **有意識地使用頂層預設**：把共用的 `extensions` / `transpilePackages` 放在根層，只在需要的地方覆寫。
* **優先使用 `chromiumBinary`／`geckoBinary` 名稱**：它們與當前的指令與型別介面一致。
* **`config` hook 保持最小**：只補上 Extension.js 一級選項尚未涵蓋的部分。

## 下一步

* 進一步了解 [可用的瀏覽器](/docs/browsers/browsers-available)。
* 進一步了解 [Rspack 設定](/docs/features/rspack-configuration)。
* 用 [瀏覽器旗標](/docs/browsers/browser-flags) 與 [瀏覽器偏好設定](/docs/browsers/browser-preferences) 調整啟動行為。
* 用 [環境變數](/docs/features/environment-variables) 管理 env 值。