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

## 参数与 flag

| flag / 参数                                                                                      | 作用                                                  | 默认值        |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------- |
| `[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 app。
* 在 Linux 上，`edge` 可能需要一个有权限的交互会话。

## 下一步

* 用 [`uninstall`](/docs/commands/uninstall) 移除受管理的浏览器。
* 在 [`dev`](/docs/commands/dev) 与 [`start`](/docs/commands/start) 中使用受管理的浏览器。
* 了解 [运行其他浏览器](/docs/browsers/running-other-browsers)：通过自定义二进制路径。