跳轉到主要內容
用同一條 JavaScript/TypeScript 管線,把擴充功能行為出貨到 background、content script 與 UI 頁面。 Extension.js 會從 manifest.json、HTML 頁面與特殊資料夾收集 script 進入點,並使用以 SWC(Speedy Web Compiler)為基礎的預設設定編譯它們。

範本範例

javascript

javascript template screenshot 採用新分頁頁面的 Vanilla JavaScript 擴充功能。
儲存庫:extension-js/templates/javascript

content

content template screenshot 注入網頁的 Vanilla JavaScript content script。
儲存庫:extension-js/templates/content

JavaScript 能力

支援的 script 進入點

在 manifest.json 中宣告 script 的範例

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

開發行為

  • Content script: Extension.js 注入 hot module replacement(HMR)/重新掛載流程,達成快速更新。
  • 擴充功能頁面: 頁面 script 走頁面 HMR 行為。
  • Background/service worker: 視變更類型而定,script 更新可能觸發整個擴充功能的 hard reload。
  • 進入點清單變更: 當 manifest 的修改新增、移除或重新命名了指令碼進入點時,正在執行的 extension dev 工作階段會自行重新啟動編譯器並重新載入擴充功能。你不需要重新啟動指令。從 4.1.41 之後的版本開始,指令碼移到另一個 manifest 鍵時工作階段也會重新啟動,例如把同一個檔案從 background.scripts 移到 background.service_worker。

Script 位置與慣例

  • 把 script 為主的擴充功能進入點放在專案根目錄的 scripts/。
  • 把帶有自己 script 的 HTML 進入點放在 pages/。
  • 維持 manifest 參考路徑穩定;不要在沒更新 manifest 的情況下移動進入檔案。

轉譯與打包預設

  • 預設使用 SWC 作為 JS/TS/JSX/TSX 的轉譯器。
  • Chromium 建置以 chrome >= 100 為目標,或以 manifest 設定的 minimum_chrome_version 為目標。
  • 從 4.2.0 之後的版本起,Firefox 建置以 firefox >= 98 為目標,或以 manifest 設定的 Gecko strict_min_version 的主版本為目標。更早的版本把沒有 strict_min_version 的 Firefox 建置編譯為 chrome >= 100。
  • 從 4.2.0 之後的版本起,Safari 建置以 safari >= 15.4 為目標。它不從 manifest 讀取版本,因為這個下限由 Xcode 專案持有。
  • 正式建置的 CSS 壓縮器使用與 script 相同的目標。
  • Extension.js 使用以瀏覽器為優先的 package.json 欄位解析(browser、module、main)。
  • Extension.js 會以可預期方式輸出進入點,預設不會把程式碼拆分到不同輸出檔。
  • 路徑解析會改寫支援的 API 中靜態的擴充功能路徑文字。

動態 import 注意事項

  • Content script 的動態 import 有執行階段限制;Extension.js 會在可能時使用 loader 後備。
  • 平台不允許在 service worker 裡使用 import() 或延後的 importScripts。到 4.1.41 為止,Chromium service worker 裡的延遲載入匯入會在執行階段失敗。從 4.1.41 之後的版本開始,建置會把它打包進 worker 檔案,這個模組仍然只在第一次被匯入時才執行。見延遲載入。

最佳實務

  • 讓進入 script 保持精簡,把功能邏輯放到共用模組。
  • 對擴充功能 API 優先使用靜態 import 路徑,讓路徑解析能安全標準化它們。
  • 避免在 content script 與 service worker 中做不必要的動態 import。
  • 在開發流程中把 manifest script 清單的編輯視為結構性變更。

後續步驟