extension.config.* 中读取 preferences,并在浏览器启动时应用。Firefox 与 Gecko 目标会得到一个 user.js 文件。Chromium 目标会得到一个预置的 Default/Preferences 文件。
工作原理
在extension.config.js(或 .mjs / .cjs)中配置 preferences:
browser.<target>.preferencescommands.dev|start|preview.preferences
preferences 能力
Firefox 与 Gecko-based 行为
配置示例
user.js 文件,并合并:
- 开发与运行时行为所需的内部基线 preferences。
- 你自定义的
preferences值(同名键以你的值为准)。
EXTENSION_USE_SYSTEM_PROFILE=true),Extension.js 不会写入受管理的 profile 文件。
Chromium 家族行为
Chromium 家族的启动(chrome、edge、chromium、chromium-based)同样会预置你的 preferences,只不过是通过 profile 而不是 user.js 文件。
启动时,Extension.js 会把你的 preferences 对象深度合并进厂商的 master-preferences 基线,并把结果一次性写入当前生效 profile 里的 Default/Preferences。只有当该文件还不存在时才会写入,所以新建的 profile 会被预置,已有的 profile 则保留自己的状态。Chrome 与 Edge 各有自己的基线对象,由你运行的目标决定使用哪一个。
由于这次写入每个 profile 只发生一次,持久化的 profile(
persistProfile
或 keepProfileChanges)不会拾取后来的 preferences 修改。删除该 profile,或者使用
临时 profile 运行,才能重新预置。browserFlagsexcludeBrowserFlagsprofile/persistProfile
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.js 或 firefox.js 中定义了大量默认值。
最佳实践
- 优先使用浏览器作用域的 preferences:把 Firefox/Gecko 的 preferences 键放在按浏览器目标划分的配置块中。
- 临时实验放进命令覆盖:短期使用的 preferences 调整放在
commands.dev里。 - 保持 profile 隔离:用不同的 profile 实现可复现的调试。
- Chromium 启动调优请用 flag:preferences 只在 profile 初次创建时预置一次,所以按次运行会变化的行为应该写成 flag。
下一步
- 进一步了解 浏览器 flag。
- 进一步了解 浏览器 profile。

