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

# Firefox 与 Gecko 运行时 preferences 配置

> 在开发期间为 Firefox 与 Gecko 设置运行时 preferences，无需修改扩展源代码。配置主页、devtools 与通知默认值。

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

在开发期间获得可复现的浏览器行为（例如主页默认值、devtools 设置或通知行为），
无需修改扩展代码。

Extension.js 会从 `extension.config.*` 中读取 `preferences`，并在启动 Firefox 与 Gecko 浏览器时应用。

## 工作原理

在 `extension.config.js`（或 `.mjs` / `.cjs`）中配置 preferences：

* `browser.<target>.preferences`
* `commands.dev|start|preview.preferences`

命令级的值可以覆盖浏览器级的默认值。

## preferences 能力

| preferences 键                  | 作用                               |
| ------------------------------ | -------------------------------- |
| `browser.<target>.preferences` | 为指定的浏览器目标设置默认 preferences。       |
| `commands.dev.preferences`     | 为 `dev` 运行设置或覆盖 preferences。     |
| `commands.start.preferences`   | 为 `start` 运行设置或覆盖 preferences。   |
| `commands.preview.preferences` | 为 `preview` 运行设置或覆盖 preferences。 |

## Firefox 与 Gecko-based 行为

### 配置示例

```js theme={null}
export default {
  browser: {
    firefox: {
      preferences: {
        "browser.startup.homepage": "https://developer.mozilla.org",
        "devtools.theme": "dark",
        "dom.webnotifications.enabled": false,
      },
    },
  },
};
```

在 Firefox/Gecko 流程中，Extension.js 会向当前生效的 profile（受管理的 profile 或显式指定的 profile）中写入一个 `user.js` 文件，并合并：

* 开发与运行时行为所需的内部基线 preferences。
* 你自定义的 `preferences` 值（同名键以你的值为准）。

如果你启用了系统 profile 模式（`EXTENSION_USE_SYSTEM_PROFILE=true`），Extension.js 不会写入受管理的 profile 文件。

## Chromium 家族行为

Chromium 家族的启动（`chrome`、`edge`、`chromium`、`chromium-based`）主要使用 **浏览器 flag**。

`preferences` 仍然可以出现在合并后的配置对象中，但 Chromium 的启动行为由 flag 与 profile 选项控制。Chromium 不使用 Firefox 风格的 `user.js` preferences 文件。

针对 Chromium 的定制，请优先使用：

* `browserFlags`
* `excludeBrowserFlags`
* `profile` / `persistProfile`

## 深色模式默认值

如果你没有显式定义相关键，Extension.js 会注入深色模式的默认值：

* Chromium 家族：深色模式启动 flag
* Firefox/Gecko 家族：深色模式 preferences 键（用于 UI 与内容的配色方案）

你显式配置的 `preferences` / flag 会覆盖这些默认值。

## 接口示例

```js theme={null}
export default {
  commands: {
    dev: {
      browser: "firefox",
      preferences: {
        "devtools.theme": "dark",
      },
    },
  },
};
```

### 自定义 profile 示例

```js theme={null}
export default {
  browser: {
    firefox: {
      profile: "path/to/custom-profile",
      preferences: {
        "browser.startup.homepage": "https://example.com",
      },
    },
  },
};
```

## 更详细的 preferences 参考

如需可用 Firefox preferences 的完整列表，可查阅 [Firefox 源代码](https://searchfox.org/mozilla-central/source/)。Mozilla 在 `all.js` 或 `firefox.js` 中定义了大量默认值。

## 最佳实践

* **优先使用浏览器作用域的 preferences**：把 Firefox/Gecko 的 preferences 键放在按浏览器目标划分的配置块中。
* **临时实验放进命令覆盖**：短期使用的 preferences 调整放在 `commands.dev` 里。
* **保持 profile 隔离**：用不同的 profile 实现可复现的调试。
* **Chromium 调优请用 flag**：在 Chromium 家族目标上，把 flag 当作主要的配置入口。

## 下一步

* 进一步了解 [浏览器 flag](/docs/browsers/browser-flags)。
* 进一步了解 [浏览器 profile](/docs/browsers/browser-profile)。