從 WXT 遷移到 Extension.js

​

哪些會變、哪些不變

• 檔案慣例的進入點（entrypoints/popup/、entrypoints/content.ts）變成真正的 manifest.json 中明確的條目。
• wxt.config.ts 中的 manifest 選項（以及 HTML 進入點裡的 <meta name="manifest.*"> 標籤）移到 manifest.json。
• defineBackground() ／ defineContentScript() 包裹器拆成一般模組。
• WXT 的自動 import 變成明確的 import。
• wxt / wxt build / wxt zip 變成 extension dev / extension build --zip。
• import.meta.env.WXT_* 環境變數變成 EXTENSION_PUBLIC_*。

​

步驟 1：安裝 Extension.js

npm install extension@latest --save-dev
npm uninstall wxt

​

步驟 2：撰寫 manifest

​

步驟 3：拆掉 defineBackground 與 defineContentScript

export default defineContentScript({
  matches: ["https://example.com/*"],
  main(ctx) {
    console.log("content script running");
  },
});

{
  "content_scripts": [
    {
      "matches": ["https://example.com/*"],
      "js": ["content/script.ts"]
    }
  ]
}

console.log("content script running");

• ctx（ContentScriptContext）： WXT 的 ctx 會在擴充功能更新、content script 被孤立時取消進行中的工作。請把綁在 ctx 上的監聽器換成一般的 addEventListener 呼叫。如果你確實依賴失效處理，可以用 chrome.runtime.id 檢查來保護長時間存活的 callback。
• createShadowRootUi ／ createIntegratedUi： 請改用一般的 DOM 程式碼掛載元件：建立一個容器元素，把它附加到頁面上，然後渲染到其中。完整模式請見 Content scripts，包括以 shadow DOM 隔離樣式的方式。

​

步驟 4：把自動 import 改為明確 import

• browser.* 呼叫：保持原樣。extension dev 預設會套用 polyfill，extension build 則需要 --polyfill。改用 chrome.* 同樣可行。
• WXT 的 storage：import { storage } from "@wxt-dev/storage" 作為獨立套件可以繼續使用。
• 框架的自動 import（來自 @wxt-dev/module-react 之類）：直接從框架套件本身 import。

​

步驟 5：環境變數與腳本

• 把 .env 檔案中的 WXT_*（以及 VITE_*）變數改名為 EXTENSION_PUBLIC_*，並把 import.meta.env.WXT_FOO 換成 process.env.EXTENSION_PUBLIC_FOO。參見環境變數。
• 更新 package.json 腳本：

{
  "scripts": {
    "dev": "extension dev",
    "build": "extension build",
    "start": "extension start"
  }
}

extension build --browser=chrome,firefox --zip

​

步驟 6：驗證

extension dev --browser=chrome

​

常見陷阱

• Manifest V2： WXT 支援把 MV2 當作建置目標，Extension.js 則以 Manifest V3 為目標。如果你仍在出貨 MV2 版本，請先完成那次遷移。參見 Manifest V3 概念。
• public/ 目錄： WXT 的 public/ 中的檔案會原封不動複製。Extension.js 對 public/ 的處理相同，從 manifest 或 HTML 參照的路徑會繼續運作。
• assets/ 與 ~／@ 別名： 請在 tsconfig.json 的 paths 中設定這些別名，或改用相對路徑 import。參見 Path resolution。
• WXT 模組（@wxt-dev/module-react、-vue、-svelte）：不再需要，因為框架支援已內建。可以對照一個全新的範本來看參考設定。
• app.config.ts 執行階段設定： 請改用你自己的模組（一個單純匯出的物件就能達到同樣效果，而且少一層框架）。

​

延伸閱讀

• Extension.js vs WXT
• 從 Plasmo 遷移
• 從 CRXJS 遷移
• 跨瀏覽器相容性
• 重新載入與 HMR