Skip to main content
在开发期间获得可复现的浏览器行为(例如主页默认值、devtools 设置或通知行为), 无需修改扩展代码。 Extension.js 会从 extension.config.* 中读取 preferences,并在浏览器启动时应用。Firefox 与 Gecko 目标会得到一个 user.js 文件。Chromium 目标会得到一个预置的 Default/Preferences 文件。

工作原理

extension.config.js(或 .mjs / .cjs)中配置 preferences:
  • browser.<target>.preferences
  • commands.dev|start|preview.preferences
命令级的值可以覆盖浏览器级的默认值。

preferences 能力

Firefox 与 Gecko-based 行为

配置示例

在 Firefox/Gecko 流程中,Extension.js 会向当前生效的 profile(受管理的 profile 或显式指定的 profile)中写入一个 user.js 文件,并合并:
  • 开发与运行时行为所需的内部基线 preferences。
  • 你自定义的 preferences 值(同名键以你的值为准)。
如果你启用了系统 profile 模式(EXTENSION_USE_SYSTEM_PROFILE=true),Extension.js 不会写入受管理的 profile 文件。

Chromium 家族行为

Chromium 家族的启动(chromeedgechromiumchromium-based)同样会预置你的 preferences,只不过是通过 profile 而不是 user.js 文件。 启动时,Extension.js 会把你的 preferences 对象深度合并进厂商的 master-preferences 基线,并把结果一次性写入当前生效 profile 里的 Default/Preferences。只有当该文件还不存在时才会写入,所以新建的 profile 会被预置,已有的 profile 则保留自己的状态。Chrome 与 Edge 各有自己的基线对象,由你运行的目标决定使用哪一个。
同名键以你的值为准,嵌套对象会逐键合并。
由于这次写入每个 profile 只发生一次,持久化的 profile(persistProfilekeepProfileChanges)不会拾取后来的 preferences 修改。删除该 profile,或者使用 临时 profile 运行,才能重新预置。
对于 Chromium 通过命令行控制的启动行为,请改用 flag:
  • browserFlags
  • excludeBrowserFlags
  • profile / persistProfile
CI 或 harness 需要在不改 extension.config.js 的情况下追加启动 flag 时,设 EXTENSION_BROWSER_FLAGS(空白分隔,例如 --headless=new)。它作用于每个被启动的浏览器,并在配置的 browserFlags 之后追加,因此 flag 重复时以环境变量为准。

深色模式默认值

如果你没有显式定义相关键,Extension.js 会注入深色模式的默认值:
  • Chromium 家族:深色模式启动 flag
  • Firefox/Gecko 家族:深色模式 preferences 键(用于 UI 与内容的配色方案)
你显式配置的 preferences / flag 会覆盖这些默认值。

接口示例

自定义 profile 示例

更详细的 preferences 参考

如需可用 Firefox preferences 的完整列表,可查阅 Firefox 源代码。Mozilla 在 all.jsfirefox.js 中定义了大量默认值。

最佳实践

  • 优先使用浏览器作用域的 preferences:把 Firefox/Gecko 的 preferences 键放在按浏览器目标划分的配置块中。
  • 临时实验放进命令覆盖:短期使用的 preferences 调整放在 commands.dev 里。
  • 保持 profile 隔离:用不同的 profile 实现可复现的调试。
  • Chromium 启动调优请用 flag:preferences 只在 profile 初次创建时预置一次,所以按次运行会变化的行为应该写成 flag。

下一步