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

# 用於受管理瀏覽器執行階段的 Install 指令

> 將受管理的瀏覽器執行階段加入 Extension.js 快取,以取得確定性的建置。支援 Chrome for Testing、Chromium、Firefox 與 Edge。

使用 `install` 把受管理的瀏覽器執行階段加入 Extension.js 的快取。

當你想為 `dev`、`build`、`start` 或 `preview` 使用一致的瀏覽器執行檔時,這個功能特別實用。它支援 Chrome for Testing、Chromium、Firefox 與 Edge。

## 何時使用 `install`

* 你需要一致、可重複的瀏覽器執行檔,以利持續整合(CI)、自動化或團隊在本機共用相同版本。
* 你想用 Chrome for Testing,而不依賴系統已安裝的 Chrome 版本。
* 你正在使用受管理的 Firefox 或 Edge 執行階段建立跨瀏覽器測試環境。

## 標準用法

單一瀏覽器使用位置引數形式:

<CodeGroup>
  ```bash npm theme={null}
  extension install <browser>
  ```

  ```bash pnpm theme={null}
  extension install <browser>
  ```

  ```bash yarn theme={null}
  extension install <browser>
  ```

  ```bash bun theme={null}
  extension install <browser>
  ```

  ```bash bun theme={null}
  extension install <browser>
  ```
</CodeGroup>

只有在你需要多目標、引擎家族或 `all` 時,才使用 `--browser`。

## Install 指令功能

| 功能       | 你可以得到的能力                                     |
| -------- | -------------------------------------------- |
| 受管理瀏覽器快取 | 在 Extension.js 的瀏覽器快取中提供穩定的安裝位置              |
| 可重複的執行階段 | 一致的執行檔,讓本機與自動化都能重現                           |
| 跨瀏覽器設置   | 為 Chrome、Chromium、Edge 與 Firefox 提供一條一致的指令流程 |
| 路徑探查     | `--where` 會顯示解析後的快取根目錄或特定瀏覽器的安裝路徑            |

## 用法

<CodeGroup>
  ```bash npm theme={null}
  extension install [browser-name] [options]
  ```

  ```bash pnpm theme={null}
  extension install [browser-name] [options]
  ```

  ```bash yarn theme={null}
  extension install [browser-name] [options]
  ```

  ```bash bun theme={null}
  extension install [browser-name] [options]
  ```

  ```bash bun theme={null}
  extension install [browser-name] [options]
  ```
</CodeGroup>

## 引數與旗標

| 旗標 / 引數                                                                                        | 用途                                                  | 預設值        |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `[browser-name]`                                                                               | 安裝單一瀏覽器目標,例如 `chrome`、`chromium`、`edge` 或 `firefox` | `chromium` |
| `--browser <chrome\|chromium\|edge\|firefox\|chromium-based\|gecko-based\|firefox-based\|all>` | 覆寫位置引數的瀏覽器名稱,並支援多目標安裝                               | 未設         |
| `--where`                                                                                      | 印出解析後的受管理快取根目錄,或特定瀏覽器的安裝路徑                          | 停用         |

## 範例

### 安裝 Chrome for Testing

```bash theme={null}
extension install chrome
```

### 在一個指令中安裝多個目標

```bash theme={null}
extension install --browser chrome,firefox
```

### 顯示 Chrome 的受管理安裝路徑

```bash theme={null}
extension install chrome --where
```

## 快取位置

預設情況下,Extension.js 會把受管理的瀏覽器存放在使用者層級、穩定的快取中:

* macOS:`~/Library/Caches/extension.js/browsers`
* Linux:`~/.cache/extension.js/browsers` 或 `$XDG_CACHE_HOME/extension.js/browsers`
* Windows:`%LOCALAPPDATA%\extension.js\browsers`

可以使用 `EXT_BROWSERS_CACHE_DIR` 覆寫快取根目錄。

## 最佳實務

* **在 CI 中使用 `install`**,以固定一致的瀏覽器執行檔,不依賴 runner 所提供的版本。
* **優先使用 `chrome`** 而非 `chromium`:Chrome for Testing 較貼近穩定版 Chrome 的行為。
* **使用 `--where`** 在撰寫受管理瀏覽器自動化前先確認快取路徑。
* `install` 只管理 Extension.js 快取內的瀏覽器。它不會更動系統上的瀏覽器安裝。

## 行為說明

* `chrome` 會安裝 Chrome for Testing,而不是依賴系統的 Google Chrome 應用程式。
* `edge` 在 Linux 上可能需要具備權限的互動式工作階段。

## 後續步驟

* 用 [`uninstall`](/docs/commands/uninstall) 移除受管理的瀏覽器。
* 搭配 [`dev`](/docs/commands/dev) 與 [`start`](/docs/commands/start) 使用受管理的瀏覽器。
* 了解 [執行其他瀏覽器](/docs/browsers/running-other-browsers) 並使用自訂執行檔路徑。