> ## 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、Firefox 与 Edge 的浏览器启动 flag

> 在 Extension.js 中使用 firefox://flags、chrome://flags 与浏览器启动 flag，在扩展开发期间控制 Chrome、Firefox 与 Edge 的运行时行为。

<AvatarBrowsers browsers={["chrome", "firefox", "edge"]} />

为调试、自动化与运行时实验控制浏览器的启动行为。

无需修改扩展源代码，即可调整浏览器的启动行为。Extension.js 会合并你在 `extension.config.*` 中配置的浏览器 flag，并在 `dev`、`preview` 与 `start` 流程中应用它们。

## Firefox 有 `firefox://flags` 吗？

Firefox 并不像 Chromium 系浏览器使用 `chrome://flags` 或 `edge://flags` 那样使用 `firefox://flags`。Firefox 通过 `about:config`（preferences）暴露运行时开关，并接受命令行传入的启动 flag。

如果你搜索过 `firefox://flags`、`firefox //flags`、`browser://flags`、`mozilla://flags` 或 `about flags firefox`，你大概率是想在扩展开发期间修改浏览器行为。在 Extension.js 中，这件事分两处来做：

* 用 [`browserFlags`](/docs/browsers/browser-flags) 配置 Extension.js 传给浏览器二进制的启动 flag。
* 用 [Firefox preferences](/docs/browsers/browser-preferences) 配置原本会写在 `about:config` 中的、可复现的 Gecko 运行时行为。

这两种方式在同一个 Extension.js 项目里都同时适用于 Chrome、Edge 与 Firefox 的扩展开发。

## 模板示例

### `new-browser-flags`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/new-browser-flags/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=d98285fcb9822b2142c4f1a71308cf91" alt="new-browser-flags template screenshot" width="3024" height="1890" data-path="images/examples/new-browser-flags/screenshot.png" />

通过一个配置了启动行为的 new-tab 扩展，直观了解浏览器 flag 的作用。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=new-browser-flags
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=new-browser-flags
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=new-browser-flags
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-browser-flags
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-browser-flags
  ```
</CodeGroup>

仓库：[extension-js/examples/new-browser-flags](https://github.com/extension-js/examples/tree/main/examples/new-browser-flags)

## 工作原理

在 `extension.config.*` 中配置 flag：

* `browser.<target>.browserFlags`
* `commands.dev|start|preview.browserFlags`
* 可选的 `excludeBrowserFlags`，用于移除默认 flag 或用户自定义的 flag（具体行为取决于目标是 Chromium 还是 Firefox）。

覆盖顺序：浏览器默认值 → 命令默认值 → CLI 选中的命令上下文。

## flag 能力

| 配置键                                    | 作用                             |
| -------------------------------------- | ------------------------------ |
| `browser.<target>.browserFlags`        | 为指定的浏览器目标设置默认启动 flag。          |
| `commands.dev.browserFlags`            | 为 `dev` 运行添加或覆盖 flag。          |
| `commands.start.browserFlags`          | 为 `start` 运行添加或覆盖 flag。        |
| `commands.preview.browserFlags`        | 为 `preview` 运行添加或覆盖 flag。      |
| `browser.<target>.excludeBrowserFlags` | 为某个目标移除匹配的默认 flag 或用户自定义 flag。 |
| `commands.<name>.excludeBrowserFlags`  | 在特定命令上下文中移除 flag。              |

### 配置示例

```js theme={null}
export default {
  browser: {
    chrome: {
      browserFlags: ["--disable-web-security", "--auto-open-devtools-for-tabs"],
      excludeBrowserFlags: ["--mute-audio"],
    },
    firefox: {
      browserFlags: ["--devtools", "--new-instance"],
      excludeBrowserFlags: ["--devtools"],
    },
  },
};
```

## Chromium 与 Firefox 行为对比

* **Chromium 家族（`chrome`、`edge`、`chromium`、`chromium-based`）**
  * 从一组内部默认 flag 出发，然后追加你的 `browserFlags`。
  * `excludeBrowserFlags` 会移除匹配的默认 flag（按精确匹配过滤）。
  * Extension.js 自己管理 `--load-extension=...`，并会从用户传入的 flag 中将其过滤掉。

* **Firefox/Gecko 家族（`firefox`、`gecko-based` / `firefox-based`）**
  * 使用用户传入的 `browserFlags`（没有像 Chromium 那样的大量默认 flag）。
  * `excludeBrowserFlags` 按前缀匹配移除用户 flag。

### Chromium 默认 flag

启动 Chromium 系浏览器时，Extension.js 会自动应用这些 flag。如果不需要其中某些，可以用 `excludeBrowserFlags` 移除。

| flag                                                       | 用途                                                  |
| ---------------------------------------------------------- | --------------------------------------------------- |
| `--no-first-run`                                           | 关闭首次运行体验                                            |
| `--disable-client-side-phishing-detection`                 | 关闭钓鱼检测                                              |
| `--disable-sync`                                           | 关闭同步以避免账号提示                                         |
| `--disable-component-extensions-with-background-pages`     | 关闭不受 `--disable-extensions` 影响的内置扩展                 |
| `--disable-default-apps`                                   | 关闭默认应用的安装                                           |
| `--disable-features=InterestFeedContentSuggestions`        | 关闭新标签页（NTP）上的 Discover feed                         |
| `--disable-features=Translate`                             | 关闭 Chrome 翻译                                        |
| `--hide-scrollbars`                                        | 在截图中隐藏滚动条                                           |
| `--mute-audio`                                             | 静音所有音频                                              |
| `--no-default-browser-check`                               | 关闭默认浏览器检查提示                                         |
| `--ash-no-nudges`                                          | 避免用户教育引导                                            |
| `--disable-search-engine-choice-screen`                    | 关闭搜索引擎选择界面                                          |
| `--disable-features=MediaRoute`                            | 关闭 Chrome Media Router 后台网络                         |
| `--use-mock-keychain`                                      | 在 Mac 上使用 mock keychain，避免阻塞性对话框                    |
| `--disable-background-networking`                          | 关闭后台网络服务                                            |
| `--disable-breakpad`                                       | 关闭崩溃转储收集                                            |
| `--disable-component-update`                               | 关闭组件更新                                              |
| `--disable-domain-reliability`                             | 关闭域名可靠性监控                                           |
| `--no-pings`                                               | 关闭超链接审计 ping                                        |
| `--enable-features=SidePanelUpdates`                       | 确保侧边栏可见                                             |
| `--disable-features=DisableLoadExtensionCommandLineSwitch` | 允许命令行使用 `--load-extension`                          |
| `--enable-unsafe-extension-debugging`                      | 允许 Chrome DevTools Protocol (CDP) 管理扩展（Chrome 126+） |
| `--silent-debugger-extension-api`                          | 抑制 "X is debugging this browser" 信息条                |

<Note>
  在 Docker、持续集成（CI）或容器化环境中，Extension.js
  还会自动应用 `--no-sandbox` 与 `--disable-setuid-sandbox`。
</Note>

## 支持的目标与参考资料

| 浏览器            | 用法                                       | 更多信息                                                                                   |
| -------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
| Chrome         | `extension dev --browser=chrome`         | [Chrome Flags](https://peter.sh/experiments/chromium-command-line-switches/)           |
| Edge           | `extension dev --browser=edge`           | [Edge Flags](https://docs.microsoft.com/en-us/deployedge/microsoft-edge-policies)      |
| Firefox        | `extension dev --browser=firefox`        | [Firefox Flags](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options) |
| Chromium-based | `extension dev --browser=chromium-based` | [Chromium Flags](https://peter.sh/experiments/chromium-command-line-switches/)         |
| Gecko-based    | `extension dev --browser=gecko-based`    | 基于 Firefox 的浏览器使用与 Firefox 相同的 flag。                                                   |

针对基于引擎的目标，需要时可使用二进制 flag：

* `--chromium-binary=...`
* `--gecko-binary=...`

## 最佳实践

* **只加必要的 flag**：尽量精简 flag 列表，避免不稳定或不可移植的配置。
* **优先使用 `excludeBrowserFlags`，而不是整体替换默认值**：只移除与你的工作流冲突的部分。
* **不要手动传入 `--load-extension`**：Extension.js 会在内部管理扩展加载相关的 flag。
* **按浏览器家族分别验证**：在 Chromium 上可用的 flag，在 Firefox 上可能无效或被忽略。

## 下一步

* 进一步了解 [浏览器 preferences](/docs/browsers/browser-preferences)。
* 进一步了解 [浏览器 profile](/docs/browsers/browser-profile)。
* 在 [可用浏览器](/docs/browsers/browsers-available) 中选择目标。
* 通过 [`extension.config.*`](/docs/features/extension-configuration) 串联 flag 配置。
* 第一次接触扩展工具链？先从 [浏览器扩展框架](/docs/compare) 概览开始。