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

運作方式

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,只是透過設定檔而不是 user.js 檔案。 啟動時,Extension.js 會把你的 preferences 物件深度合併進廠商的 master-preferences 基準,並將結果一次性寫入目前設定檔中的 Default/Preferences。只有在該檔案尚不存在時才會寫入,因此全新的設定檔會被預先寫入,既有的設定檔則保留自己的狀態。Chrome 與 Edge 各自有專屬的基準物件,由你執行的目標決定採用哪一個。
發生鍵衝突時以你的值為準,巢狀物件則逐鍵合併。
由於寫入每個設定檔只發生一次,持久化的設定檔(persistProfilekeepProfileChanges)不會採用後續的偏好修改。請刪除該設定檔,或改用 暫時性設定檔執行,才能重新寫入。
至於 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 啟動行為:偏好只會在設定檔建立時寫入一次,因此每次執行都可能改變的行為應該交給旗標。

後續步驟