支援 HMR 與 manifest 進入點的 content script

​

Content script 能力

​

範本範例

​

content

npx extension@latest create my-extension --template=content

pnpx extension@latest create my-extension --template=content

yarn dlx extension@latest create my-extension --template=content

bunx extension@latest create my-extension --template=content

bunx extension@latest create my-extension --template=content

​

content-react

npx extension@latest create my-extension --template=content-react

pnpx extension@latest create my-extension --template=content-react

yarn dlx extension@latest create my-extension --template=content-react

bunx extension@latest create my-extension --template=content-react

bunx extension@latest create my-extension --template=content-react

​

支援的 manifest 欄位

​

Content script 宣告範例

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["./scripts/content-script.ts"],
      "css": ["./styles/content-style.css"]
    }
  ]
}

​

撰寫合約

• 模組應以 export default 匯出一個同步函式。
• 該函式應執行設定工作。
• 它可以回傳一個同步的清理 callback。
• Extension.js 不支援將 class 作為 default export。

• 被 manifest.json > content_scripts[*].js 參考的檔案。
• 你放在專案 scripts/ 資料夾中、用作 script 進入點的檔案。

​

有效形式

export default function main() {
  return () => {};
}

const main = () => {};
export default main;

​

無效形式

export default class App {}

export default {};

​

對於 async content script 的建議

​

違反合約會發生什麼事

• 沒有 default export：Extension.js 會在開發期警告並跳過掛載。
• Default export 不是函式：Extension.js 會在開發期警告並跳過掛載。
• Default export 回傳一個 Promise：模組仍會執行，但 Extension.js 不會把該 Promise 視為清理函式。

​

執行階段包裹器行為

• Extension.js 用掛載／runtime 輔助器包裹 content script 模組。
• 在開發模式中，Extension.js 會加上 HMR accept／dispose 行為與重新掛載流程。
• CSS 更新會在開發期觸發重新掛載事件（__EXTENSIONJS_CSS_UPDATE__）。
• Extension.js 會尊重 manifest 中的 run_at 時機設定。

​

多進入點 content script

​

content-multi-one-entry

npx extension@latest create my-extension --template=content-multi-one-entry

pnpx extension@latest create my-extension --template=content-multi-one-entry

yarn dlx extension@latest create my-extension --template=content-multi-one-entry

bunx extension@latest create my-extension --template=content-multi-one-entry

bunx extension@latest create my-extension --template=content-multi-one-entry

​

content-multi-three-entries

npx extension@latest create my-extension --template=content-multi-three-entries

pnpx extension@latest create my-extension --template=content-multi-three-entries

yarn dlx extension@latest create my-extension --template=content-multi-three-entries

bunx extension@latest create my-extension --template=content-multi-three-entries

bunx extension@latest create my-extension --template=content-multi-three-entries

​

scripts/ 資料夾行為

• Script 進入檔案如果需要掛載行為，仍應 export 一個 default function。
• 在 watch mode 中，Extension.js 把在 scripts/ 底下新增或刪除受支援檔案視為結構性變更。
• 當該進入點集合改變時，Extension.js 可能需要重新啟動開發伺服器。

​

輸出路徑

content_scripts/
├── content-0.js          # production
├── content-0.abcd1234.js # development (hash-based cache busting)
├── content-0.css
└── ...

​

MAIN world 注意事項

​

content-main-world

npx extension@latest create my-extension --template=content-main-world

pnpx extension@latest create my-extension --template=content-main-world

yarn dlx extension@latest create my-extension --template=content-main-world

bunx extension@latest create my-extension --template=content-main-world

bunx extension@latest create my-extension --template=content-main-world

• world: "MAIN" 僅限 Chromium。 Firefox 不支援 world 欄位並會忽略它。你的腳本在 Firefox 仍會以 isolated world 執行。
• 跨瀏覽器的 MAIN world 行為： 使用 chromium: manifest 前綴，僅針對 Chromium 目標宣告它。然後為 Firefox 提供 isolated world 後備。
• 在開發期，MAIN world 腳本透過內部 bridge 機制載入程式碼 chunk 與解析 public path。
• 在 MAIN world 中無法使用擴充功能 API（chrome.runtime、chrome.storage 等）；只能存取頁面情境的全域變數。
• 把 MAIN world 視為進階路徑。在每個目標瀏覽器上盡早驗證行為。

​

Isolated vs MAIN 快速範例

{
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["./scripts/isolated.ts"]
    },
    {
      "matches": ["<all_urls>"],
      "js": ["./scripts/main-world.ts"],
      "world": "MAIN"
    }
  ]
}

​

跨瀏覽器的 MAIN world 模式

{
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["./scripts/isolated.ts"]
    },
    {
      "matches": ["<all_urls>"],
      "chromium:js": ["./scripts/main-world.ts"],
      "chromium:world": "MAIN"
    }
  ]
}

​

比對與執行建議

• 把 matches 保持在功能所允許的最小範圍。
• 只在功能確實需要時才加入 exclude_matches、all_frames 或 match_about_blank。
• 把 run_at 與 world 視為功能合約的一部分，而不是實作細節。
• 變更 content script 的執行位置時，重新測試權限與 host permission 的範圍。

​

開發行為

• 編輯 content script 程式碼通常會走包裹器驅動的 HMR／重新掛載流程。
• 純 CSS 進入點會獲得開發輔助行為，讓樣式更新得以傳播。
• 如果 manifest 中的 content script 進入點清單改變，Extension.js 可能需要重新啟動開發伺服器。

​

最佳實務

• 讓 content script 進入檔案保持小巧，把邏輯委派給共用模組。
• 仔細限定 selector／樣式範圍，避免與主機頁面衝突。
• 當行為依賴執行時機／情境時，明確設定 run_at 與 world。
• 在開發流程中，把 manifest content script 清單變更視為結構性變更。
• 透過經過驗證的 messaging 傳遞來自頁面的資料，而不是直接在 content script 中執行特權工作。
• 預設使用 isolated world，只有在嚴格需要頁面情境時才改用 MAIN。

​

後續步驟

• 在 dev 更新行為中了解更新結果。
• 透過 Messaging 設計跨情境通訊。
• 在權限與 host 權限中檢視存取範圍。
• 了解 web-accessible resources。
• 繼續閱讀開發中的 locale。