manifest.json、HTML 頁面與特殊資料夾收集 script 進入點,並使用以 SWC(Speedy Web Compiler)為基礎的預設設定編譯它們。
範本範例
javascript

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 設定的 Geckostrict_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 清單的編輯視為結構性變更。
後續步驟
- 在 dev 更新行為中了解更新結果。
- 透過 Special folders 學習如何組織檔案。
- 繼續閱讀 background script 與 service worker。

