跳轉到主要內容
用一份設定檔同時設定瀏覽器預設值、指令行為與 bundler 客製化。 跨團隊共用瀏覽器預設、指令選項與建置設定，不再重複輸入 CLI 旗標。Extension.js 會從專案根目錄讀取 extension.config.js（或 .mjs / .cjs），並套用到每個指令與 bundler。

​
運作方式

在專案根目錄（通常和 package.json 同層）加上 extension.config.js。 支援的檔名：
  • extension.config.js
  • extension.config.mjs
  • extension.config.cjs
頂層的鍵：
鍵說明
browser依瀏覽器目標分鍵的瀏覽器專屬預設值。
commands各指令的預設值（dev、start、preview、build）。
extensions跨指令套用的附屬擴充功能（僅載入）。
transpilePackages打包前要先編譯的套件（在 monorepo／workspace 設定中很實用）。
config用來擴充／覆寫產生出的 Rspack 設定的 hook。

​
設定檔的環境載入

extension.config.* 在 Node 中執行，應該從 process.env.* 讀取值。
  • Extension.js 在評估 extension.config.* 之前，會預先載入 env 檔。
  • 它會先檢查專案資料夾。
  • 在 monorepo 中，若 Extension.js 找不到專案本地的 .env*，會 fallback 到最近的 workspace 根目錄，也就是包含 pnpm-workspace.yaml 的資料夾。
  • 比起在設定檔中匯入 dotenv，建議優先使用內建的 env 預載。

​
瀏覽器設定

需要為每個目標設定不同的瀏覽器預設值？使用 browser： 
export default {
  browser: {
    chrome: {
      profile: "path/to/profile",
      preferences: { darkMode: true },
      browserFlags: ["--disable-web-security"],
      excludeBrowserFlags: ["--mute-audio"],
    },
    "chromium-based": {
      chromiumBinary: "/path/to/brave-or-other-chromium-binary",
    },
    firefox: {
      geckoBinary: "/path/to/firefox",
    },
  },
};
支援的瀏覽器鍵包括：chrome、edge、firefox、chromium、chromium-based、gecko-based、firefox-based。 常用的瀏覽器欄位：
  • profile、persistProfile
  • preferences
  • browserFlags、excludeBrowserFlags
  • chromiumBinary、geckoBinary
  • extensions（僅載入的附屬擴充功能）

​
瀏覽器目標能力

鍵作用
profile設定瀏覽器啟動時使用的 profile 路徑（或行為）。
persistProfile在多次執行間沿用 profile 資料。
preferences套用瀏覽器偏好設定覆寫。
browserFlags在瀏覽器程序啟動時加入旗標。
excludeBrowserFlags移除不想使用的預設啟動旗標。
chromiumBinary使用自訂的 Chromium 系二進位檔路徑。
geckoBinary使用自訂的 Gecko/Firefox 二進位檔路徑。
extensions與主擴充功能一起載入附屬擴充功能。

​
指令設定

用 commands 定義每個指令的預設值： 
export default {
  transpilePackages: ["@workspace/ui"],
  commands: {
    dev: {
      browser: "chrome",
      polyfill: true,
      logLevel: "info",
      persistProfile: true,
      browserFlags: ["--headless=new"],
      extensions: { dir: "./extensions" },
    },
    start: {
      browser: "firefox",
      source: "https://example.com",
    },
    preview: {
      browser: "edge",
      noBrowser: false,
    },
    build: {
      browser: "chrome",
      zip: true,
      zipSource: true,
      zipFilename: "my-extension.zip",
      transpilePackages: ["@workspace/ui", "@workspace/icons"],
    },
  },
};
注意事項：
  • Extension.js 會把頂層的 extensions 與 transpilePackages 合併進各指令的預設值。
  • 各指令的值會覆寫頂層的值。
  • start 指令會在內部依序執行 build 與 preview。Extension.js 會套用 commands.start 中的設定，包括 profile、browserFlags 與 startingUrl 等瀏覽器啟動選項。你也可以把建置專屬的設定放在 commands.build。

​
指令共用能力

鍵適用於作用
browserdev、start、preview、build設定瀏覽器或瀏覽器家族目標。
profiledev、start、preview設定瀏覽器 profile 路徑／行為。
persistProfiledev、start、preview在多次執行間沿用瀏覽器 profile 資料。
chromiumBinarydev、start、preview使用自訂的 Chromium 系二進位檔。
geckoBinarydev、start、preview使用自訂的 Gecko 系二進位檔。
polyfilldev、start、build在相關情境啟用相容性 polyfill 行為。
preferencesdev、start、preview套用瀏覽器偏好設定覆寫。
browserFlagsdev、start、preview在瀏覽器程序啟動時加入旗標。
excludeBrowserFlagsdev、start、preview移除不想使用的預設啟動旗標。
startingUrldev、start、preview在瀏覽器啟動時開啟指定 URL。
portdev、start、preview設定 runner／DevTools 連接埠。
hostdev、start、preview設定開發伺服器主機。Docker／dev container 請用 0.0.0.0。
noBrowserdev、start、preview停用瀏覽器啟動。
extensionsdev、start、preview、build載入附屬擴充功能（或擴充功能清單）。
installdev、start、build執行前先安裝缺少的依賴項。
transpilePackagesdev、start、preview、build編譯指定的 workspace／外部套件。

​
build 指令能力

鍵作用
zip產生封裝後的 zip 產物。
zipSource為審查／合規流程額外產出原始碼 bundle／封存檔。
zipFilename設定自訂的 zip 輸出檔名。
silent減少建置記錄輸出。

​
dev 指令能力

鍵作用
noOpen啟動開發伺服器但不自動開啟瀏覽器。
source從遠端來源 URL 啟用原始碼檢查流程。
watchSource當監看的更新發生時，重新執行原始碼檢查。
sourceFormat設定原始碼輸出格式（pretty、json、ndjson）。
sourceSummary輸出精簡的原始碼摘要。
sourceMeta在原始碼輸出中包含頁面中繼資料。
sourceProbe用特定 CSS 選擇器探查原始碼輸出。
sourceTree控制精簡的擴充功能樹狀輸出。
sourceConsole在原始碼輸出中包含 console 摘要。
sourceDom在原始碼輸出中包含 DOM 快照／差異。
sourceMaxBytes限制原始碼輸出 payload 的大小。
sourceRedact控制原始碼遮蔽策略。
sourceIncludeShadow控制 Shadow DOM 的包含策略。
sourceDiff在原始碼監看更新時包含 diff 中繼資料。

​
記錄能力

鍵適用於作用
logsdev、start、preview設定最低記錄等級（off 到 all）。
logContextdev、start、preview依情境過濾記錄（background、content 等）。
logFormatdev、start、preview設定輸出格式（pretty、json、ndjson）。
logUrldev、start、preview依 URL 模式過濾記錄。
logTabdev、start、preview依分頁 ID 過濾記錄。

​
Rspack 設定

需要進階的 bundler 客製化？使用 config 來修補產生出的 Rspack 設定： 
export default {
  config: (config) => {
    config.module.rules.push({
      test: /\.mdx$/,
      use: ["babel-loader", "@mdx-js/loader"],
    });
    return config;
  },
};
config 也可以是物件，Extension.js 會把它合併到產生出的設定之上。

​
完整範例

export default {
  browser: {
    chrome: { browser: "chrome", profile: "default" },
    firefox: { browser: "firefox", persistProfile: true },
    "chromium-based": {
      browser: "chromium-based",
      chromiumBinary:
        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    },
  },
  commands: {
    dev: {
      browser: "chrome",
      polyfill: true,
      host: "0.0.0.0",
      extensions: { dir: "./extensions" },
    },
    start: { browser: "edge" },
    preview: { browser: "firefox" },
    build: {
      zipFilename: "extension.zip",
      zip: true,
      zipSource: true,
    },
  },
  extensions: { dir: "./extensions" },
  transpilePackages: ["@workspace/ui"],
  config: (config) => config,
};

​
最佳實務

  • 瀏覽器專屬值放在 browser：讓指令定義專注於工作流程，而非瀏覽器內部細節。
  • 有意識地使用頂層預設：把共用的 extensions / transpilePackages 放在根層，只在需要的地方覆寫。
  • 優先使用 chromiumBinary／geckoBinary 名稱：它們與當前的指令與型別介面一致。
  • config hook 保持最小：只補上 Extension.js 一級選項尚未涵蓋的部分。

​
下一步