跳轉到主要內容
打造整合頁面的擴充功能行為,同時保有可靠的 JS 與 CSS 更新開發循環。 Extension.js 從 manifest.json 編譯 content script 進入點,並用包裹器包起來以支援執行階段掛載與 hot module replacement(HMR)行為。最後會輸出可預測的 content_scripts/* 檔案。

Content script 能力

範本範例

content

content template screenshot 以 vanilla JS 的最小 content script 設定。
儲存庫:extension-js/templates/content

content-react

content-react template screenshot 透過 content script 把 React 驅動的 UI 注入到網頁中。
儲存庫:extension-js/templates/content-react

支援的 manifest 欄位

Content script 宣告範例

在 manifest.json 中宣告 content script 的範例:

撰寫合約

對於每一個類似 content script 的進入點,Extension.js 期待採用以「掛載」為模式的 default export。這是一個會設定行為、並可選擇性回傳清理 callback 的函式:
  • 模組應以 export default 匯出一個同步函式。
  • 該函式應執行設定工作。
  • 它可以回傳一個同步的清理 callback。
  • Extension.js 不支援將 class 作為 default export。
這套規則適用於:
  • 被 manifest.json > content_scripts[*].js 參考的檔案。
  • 你放在專案 scripts/ 資料夾中、用作 script 進入點的檔案。

有效形式

無效形式

對於 async content script 的建議

即使功能內部會做非同步工作,default export 仍應保持同步。在函式內部啟動非同步工作,並回傳同步的清理函式。 為什麼這很重要:Extension.js 會在開發期重新掛載 content script。若沒有清理函式,可能會重複出現 UI、事件監聽器、observer 與 timer。

違反合約會發生什麼事

  • 沒有 default export:Extension.js 會在開發期警告並跳過掛載。
  • Default export 不是函式:Extension.js 會在開發期警告並跳過掛載。
  • Default export 回傳一個 Promise:模組仍會執行,但 Extension.js 不會把該 Promise 視為清理函式。
如果你的 content script 看起來編譯成功但從未掛載,請先檢查 default export。

整個擴充功能重新載入後什麼會留下

當 extension dev 中的一次修改讓整個擴充功能重新載入時,保持開啟的分頁裡仍然留著重新載入之前的那份 content script 副本。這個舊副本的去向取決於瀏覽器引擎:
  • Chromium 會讓舊副本在開啟的分頁裡和新副本一起繼續執行,計時器和 listener 也包括在內,直到分頁重新載入為止。它的 chrome.runtime.id 已經不存在,也不會為它呼叫任何清理,即使腳本的預設匯出回傳了清理函式也一樣。
  • Firefox 會丟棄舊副本。不會為它呼叫任何清理,它也不會再執行。
在這兩個引擎上,舊副本加到頁面上的東西都會留在那裡,直到下一個副本把它移除。 要在 Chromium 上結束舊副本,請重新載入分頁。或者讓長時間執行的工作在 chrome.runtime.id 消失後停下來:
對於沒有預設匯出的腳本,開發工作階段的警告在 Chromium 上也是這樣說的:
把你的腳本加到頁面上的一切都放在一個標記了 data-extension-root 的 host 元素底下。下一個副本啟動時,Extension.js 會移除舊副本留下的這些 host,在 Chromium 和 Firefox 上都是如此:
這次清掃需要一個 dev 工作階段。正式建置沒有需要復原的重新載入。

執行階段包裹器行為

  • Extension.js 用掛載/runtime 輔助器包裹 content script 模組。
  • wrapper 在正式建置中同樣生效,沒有選項可以關閉它。
  • 從 4.1.41 之後的版本起,wrapper 在你自己的 loader 之後執行。見 Loader 順序。
  • 在開發模式中,Extension.js 會加上 HMR accept/dispose 行為與重新掛載流程。
  • CSS 更新會在開發期觸發重新掛載事件(__EXTENSIONJS_CSS_UPDATE__)。
  • Extension.js 會尊重 manifest 中的 run_at 時機設定。

多進入點 content script

你可以在單一 manifest 中宣告多個 content script 進入點。每個進入點都會獨立編譯,並擁有自己的 match patterns、執行時機與 world 設定。

content-multi-one-entry

content-multi-one-entry template screenshot 把多個 content script 包在同一個 content_scripts manifest 進入點底下。
儲存庫:extension-js/templates/content-multi-one-entry

content-multi-three-entries

content-multi-three-entries template screenshot 三個獨立的 content_scripts manifest 進入點,各自有獨立的 match patterns。
儲存庫:extension-js/templates/content-multi-three-entries

傳統的多檔案進入點

當一個 content_scripts.js 陣列列出多個沒有 import 也沒有 export 的純 JavaScript 檔案時,Extension.js 會把它們串接成一個 bundle。把每個檔案當成獨立模組打包會破壞它們。瀏覽器會依序把這些傳統檔案注入到同一個共享作用域,而串接正好保留了這個行為:
  • 跨檔案的隱含全域變數仍然可用。第一個檔案中的頂層 var 或函式對下一個檔案依然可見。
  • 每個原始檔都會註冊為建置相依,所以儲存這一組中的任何檔案都會觸發重新建置。
  • 輸出的 source map 指向你真正的檔案與行號,因此錯誤可以追回原始程式碼。
  • 串接群組中的原始 .ts 檔案會在串接前用內建的 SWC 去除型別。
使用 import 或 export 的進入點維持一般的模組打包。

scripts/ 資料夾行為

scripts/ 資料夾用來放沒有被任何 HTML 頁面進入點宣告的 script 進入點。實務上,這些進入點遵循與 content script 相同的 default export 模式。 也就是說,scripts/ 不是用來放零散 JavaScript 檔案的通用資料夾:
  • Script 進入檔案如果需要掛載行為,仍應 export 一個 default function。
  • 在 watch mode 中,Extension.js 把在 scripts/ 底下新增或刪除受支援檔案視為結構性變更。
  • 當 manifest 的修改新增、移除或重新命名了指令碼進入點時,正在執行的 extension dev 工作階段會自行重新啟動編譯器並重新載入擴充功能。你不需要重新啟動指令。從 4.1.41 之後的版本開始,指令碼移到另一個 manifest 鍵時工作階段也會重新啟動,例如把同一個檔案從 background.scripts 移到 background.service_worker。

輸出路徑

Extension.js 依 manifest 索引將 content script 進入點標準化:
在開發模式中,content script 的 JS 檔名會帶有短雜湊後綴(例如 content-0.abcd1234.js)。這會強迫瀏覽器在每次重新建置後載入新的 chrome-extension:// URL。 Chrome 對擴充功能資源的快取相當積極,所以加上雜湊可以避免拿到舊程式碼。Production 建置會使用乾淨的 content-0.js 命名。

MAIN world 注意事項

content-main-world

透過將 UI 直接注入到頁面情境的可運作範例,看看 MAIN world content script 的實際表現:
儲存庫:extension-js/templates/content-main-world
  • world: "MAIN" 在 Chrome 111、Firefox 128 與 Safari 18 及更新版本上可用。 在這三種瀏覽器上,腳本都在頁面自己的 JavaScript world 中執行。在 Firefox 上,Manifest V2 與 Manifest V3 都是如此。
  • MAIN world 腳本沒有擴充功能 API。 chrome.runtime、chrome.storage 等在那裡都無法使用,只能存取頁面情境的全域變數。請替它搭配一個 isolated world 腳本來與擴充功能溝通。
  • 只有面向更舊的瀏覽器時才值得用瀏覽器前綴。 只有在必須支援早於上述版本的瀏覽器時,才使用 chromium:world 並搭配 isolated world 後備。
  • scripts/ 檔案也可以在 MAIN world 中執行。 在執行階段用 world: "MAIN" 註冊或注入它。請見在執行階段注入腳本。
  • 從 4.2.0 起,編譯失敗的 MAIN world 腳本不會發布損壞的產物。
  • 把 MAIN world 視為進階路徑。在每個目標瀏覽器上盡早驗證行為。

isolated world 橋接

MAIN world 腳本無法呼叫擴充功能 API,因此 Extension.js 會為每個 MAIN 群組搭配一個可以呼叫的輔助腳本。請預期建置後的 manifest 在這裡會和你的原始碼不同:
  • dist 中的 manifest 會比原始碼包含更多 content_scripts 進入點。Extension.js 會在每個 MAIN 群組之前插入一個 isolated world 橋接進入點。
  • 橋接進入點的資產索引排在你的進入點之後。你的 content_scripts/content-N 輸出仍保留產生它們的來源進入點索引。
  • 橋接透過 runtime.getURL 解析擴充功能 URL,並把 MAIN world 的程式碼 chunk 注入頁面。從 4.1.39 之後的版本起,它在 Firefox 上不再注入任何東西,MAIN world 腳本會自己載入它的 chunk。
  • 橋接在處理訊息之前會驗證 event.source 是否為同一個 window。
  • 它只會注入擴充功能協定的 URL(chrome-extension://、moz-extension://)或相對路徑,絕不會注入任意遠端 URL。

在 Firefox 上頁面讀得到的擴充功能 URL

在 Firefox 上,你的 moz-extension:// 來源帶有一個每次安裝都不同的 id。頁面一旦取得它,就能再次認出同一個瀏覽器。 從 4.1.39 之後的版本起,建置把這個來源交給 MAIN world 腳本時,不會把它寫進頁面的 DOM。頁面無法從這次交接中讀到這個來源。 這只涵蓋建置自己的內部通道。你的腳本放進 DOM 的任何東西,頁面都讀得到:
  • 指向擴充功能資源的 <img src> 或 <link href>。
  • 對擴充功能 URL 的 fetch,前提是頁面已經改寫了 fetch。
  • 元件的 <style> 區塊,其中的 url() 指向擴充功能資源。這份樣式表會落在 document 裡的一個 <style> 元素中。
不要讓 MAIN world 腳本把擴充功能 URL 帶進頁面,否則就要接受這種暴露。要避免暴露,請把這部分工作放到 isolated world 腳本裡完成,再把資料傳過去。 頁面可以竄改這次交接。把交接換成自己版本的頁面什麼也拿不到,而你的腳本隨後也載入不了任何資源與 chunk。如果頁面在橋接執行之前就鎖住了這次交接,建置會退回到 document 上,頁面在那裡讀得到這個來源。

Isolated vs MAIN 快速範例

預設使用 isolated world。只有在你需要頁面情境存取時才使用 MAIN,並要考量擴充功能 API 與 runtime 的限制。

用前綴支援更舊的瀏覽器

在 Chrome 111、Firefox 128 與 Safari 18 及更新版本上,上面快速範例裡不帶前綴的 world 鍵就足夠了。早於 128 的 Firefox 會忽略 world 鍵,並在 isolated world 中執行腳本。如果你必須支援這樣的版本,使用瀏覽器專屬前綴,僅在 Chromium 上宣告 MAIN world,並為 Firefox 提供 isolated 後備。這樣一來,每個 Firefox 版本都會執行後備腳本,包括那些支援 MAIN 的版本:
Firefox 會完全略過 chromium: 前綴的欄位,所以第二個進入點到達 Firefox 建置時既沒有 js 也沒有 css。Firefox 從它那裡什麼都拿不到。建置會把這個進入點從 Firefox manifest 中略去,並印出原因:
當 Firefox 需要在這些 matches 上執行 content script 時,在同一個進入點上加一個一般的 js。帶前綴的鍵會覆寫同名的一般鍵,所以 Chromium 仍然在 MAIN world 使用 chromium:js,而 Firefox 在 isolated world 執行一般的 js。這樣一個進入點就能同時涵蓋兩種瀏覽器,建置也不會印出警告:
一般的 js 是每個目標都會讀取的基礎鍵,所以在任何不解析 chromium: 的瀏覽器上,這個進入點都保持完整。firefox:js 也能保留這個進入點,但只在 Gecko 目標上生效,而前綴頁面的規則是:以一般鍵為基礎,只替例外加上前綴。

比對與執行建議

瀏覽器仍然掌控 content script 在哪裡執行。Extension.js 會打包檔案,但 manifest 進入點仍然定義腳本執行的時機與位置。
  • 把 matches 保持在功能所允許的最小範圍。
  • 只在功能確實需要時才加入 exclude_matches、all_frames 或 match_about_blank。
  • 把 run_at 與 world 視為功能合約的一部分,而不是實作細節。
  • 變更 content script 的執行位置時,重新測試權限與 host permission 的範圍。

開發行為

  • 編輯 content script 程式碼通常會走包裹器驅動的 HMR/重新掛載流程。
  • 純 CSS 進入點會獲得開發輔助行為,讓樣式更新得以傳播。
  • 當 manifest 的修改新增、移除或重新命名了指令碼進入點時,正在執行的 extension dev 工作階段會自行重新啟動編譯器並重新載入擴充功能。你不需要重新啟動指令。從 4.1.41 之後的版本開始,指令碼移到另一個 manifest 鍵時工作階段也會重新啟動,例如把同一個檔案從 background.scripts 移到 background.service_worker。

最佳實務

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

後續步驟

模板示範