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 运行,才能重新预置。保留的 profile 上的启动偏好
比会话活得更久的 profile(例如--profile <path>)会记住它打开的页面。下一次启动时,Chrome 会抢在你的扩展之前恢复上一次运行的页面。
从 4.1.39 之后的版本起,dev 会在这样的 profile 里把 session.restore_on_startup 设为 5,这样浏览器会打开新标签页。会话通过浏览器只写一次这个值,之后它就留在那个 profile 里。身份卡会写明这一点:
left to the browser, preferences sets it。已经有这个值的 profile 会一直保留它,直到你在 chrome://settings 里修改“启动时”。临时 profile 在退出时会被删除,所以会话不会往里面写任何东西。
对于 Chromium 通过命令行控制的启动行为,请改用 flag:
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。

