Skip to main content
在開發期間取得可重複的瀏覽器行為(例如首頁預設值、開發者工具設定或通知行為), 不需修改擴充功能程式碼。 Extension.js 會從 extension.config.* 讀取 preferences,並在啟動 Firefox 與 Gecko 瀏覽器時套用。

運作方式

extension.config.js(或 .mjs / .cjs)中設定偏好:
  • browser.<target>.preferences
  • commands.dev|start|preview.preferences
指令層級的值可以覆寫瀏覽器層級的預設值。

偏好設定功能

Firefox 與 Gecko 系列的行為

設定範例

在 Firefox/Gecko 流程中,Extension.js 會在使用中的設定檔(由管理的設定檔或明確指定的設定檔)裡寫入一份 user.js,並合併下列內容:
  • 開發與執行階段行為所需的內部基準偏好。
  • 你自訂的 preferences 值(發生鍵衝突時以你的值為準)。
如果你啟用系統設定檔模式(EXTENSION_USE_SYSTEM_PROFILE=true),Extension.js 不會寫入受管理的設定檔。

Chromium 系列的行為

Chromium 系列的啟動(chromeedgechromiumchromium-based)主要使用瀏覽器旗標 preferences 仍可存在於合併後的設定物件中,但實際控制 Chromium 啟動行為的是旗標與設定檔選項。Chromium 並不使用 Firefox 風格的 user.js 偏好檔案。 針對 Chromium 客製,建議優先使用:
  • browserFlags
  • excludeBrowserFlags
  • profile / persistProfile
CI 或 harness 需要在不改 extension.config.js 的情況下追加啟動 flag 時,設 EXTENSION_BROWSER_FLAGS(空白分隔,例如 --headless=new)。它作用於每個被啟動的瀏覽器,並在設定的 browserFlags 之後追加,因此 flag 重複時以環境變數為準。

深色模式預設值

除非你已自行定義對應的鍵,否則 Extension.js 會注入深色模式的預設值:
  • Chromium 系列:深色模式的啟動旗標
  • Firefox/Gecko 系列:深色模式偏好鍵(套用於 UI 與內容色彩配置)
你明確指定的 preferences/旗標會覆蓋這些預設值。

介面範例

自訂設定檔的範例

更詳盡的偏好設定參考

若想查看可用的 Firefox 偏好完整清單,可以瀏覽 Firefox 原始碼。Mozilla 將許多預設值定義在 all.jsfirefox.js

最佳實務

  • 優先採用瀏覽器層級的偏好:把 Firefox/Gecko 的偏好鍵集中在以瀏覽器為目標的設定區塊中。
  • 以指令層級覆寫做臨時實驗:短期的偏好調整放進 commands.dev
  • 保持設定檔彼此隔離:使用不同的設定檔讓除錯結果可重現。
  • 以旗標來調整 Chromium:在 Chromium 系列目標上,將旗標視為主要的設定面。

後續步驟