跳转到主要内容
在开发期间获得可复现的浏览器行为（例如主页默认值、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 行为

​
配置示例

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 会覆盖这些默认值。

​
接口示例

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

​
自定义 profile 示例

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

​
更详细的 preferences 参考

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

​
最佳实践

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

​
下一步