跳轉到主要內容
用一份設定檔同時設定瀏覽器預設值、指令行為與 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.js 從 extension 套件匯出 FileConfig 型別，讓編輯器能對你的設定自動完成與型別檢查。用 JSDoc @type 標籤標註匯出——它可在 extension.config.js、.mjs 與 .cjs 中運作,且不需要建置步驟： 
/** @type {import('extension').FileConfig} */
export default {
  browser: {
    chrome: { profile: "path/to/profile" },
  },
};

​
設定檔的環境載入

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",
    },
    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啟動開發伺服器但不自動開啟瀏覽器。

​
記錄能力

鍵適用於作用
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 一級選項尚未涵蓋的部分。

​
下一步