Background script 與 MV3 service worker

​

範本範例

​

action

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

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

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

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

deno run -A npm:extension@latest create my-extension --template=action

​

ai-chatgpt

npx extension@latest create my-extension --template=ai-chatgpt

pnpx extension@latest create my-extension --template=ai-chatgpt

yarn dlx extension@latest create my-extension --template=ai-chatgpt

bunx extension@latest create my-extension --template=ai-chatgpt

deno run -A npm:extension@latest create my-extension --template=ai-chatgpt

​

Background 能力

​

Background script 支援

​

Background script 宣告範例

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "background": {
    "service_worker": "./scripts/background.ts"
  }
}

​

開發行為

• Extension.js 追蹤 service worker／原始碼變更，並可觸發整個擴充功能的 hard reload。
• 影響 background 進入點的 manifest 變更會觸發「需要重新啟動」的診斷訊息。
• 啟動瀏覽器的 plugin 會套用對應平台（Chromium／Firefox）的 hard reload 策略。
• Extension.js 對結構性進入點變更的處理比一般模組編輯更嚴格。

​

Firefox：service worker 轉譯為 event page

​

Chromium：scripts 轉譯為 service worker

​

Safari：使用 background 頁面，而不是 service worker

// Throws on Safari and takes the whole background context with it.
chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });

// Safe on every target.
chrome.sidePanel?.setPanelBehavior({ openPanelOnActionClick: true });

​

MV3 service worker 生命週期

• 記憶體中的狀態可能會在事件之間消失。
• 設計長時間執行的工作時，要以事件為核心，而不是以程序常駐為前提。
• 啟動流程要保持輕量、可預測。
• 你的程式碼應該從 storage 還原重要狀態，或以安全方式重新計算。

​

輸出行為

• background/service_worker.js
• background/scripts.js

​

Module 與 classic 注意事項

• background.type: "module" 採用 module worker 語義。
• Classic service worker 模式採用基於 importScripts 的 chunk 載入行為。
• 避免在 background 程式碼中使用動態 import，尤其是必須在啟動時立即載入的部分。

​

執行階段載入的檔案

• classic service worker 的 importScripts(...) 相依項目。 字串字面值參數會相對於輸出的 worker 位置遞迴解析（相依項目本身也可以呼叫 importScripts），因此即使 worker 移動到 background/service_worker.js，相對於 worker 的 URL 仍然可用。由 wasm-bindgen 膠水程式碼載入的 WebAssembly 同層檔案（*_bg.wasm）會與它的載入器一起發布。
• chrome.scripting.executeScript({files: [...]}) 與 insertCSS({files: [...]}) 的內容。 只在 files: 陣列中被參照、而未在 manifest 的 content_scripts 中宣告的檔案，會依其擴充功能根目錄下的路徑原樣複製。

​

建議的架構

• 讓 background 進入點保持精簡，把功能邏輯放到共用模組。
• 把 background 情境當成 messaging、storage 存取與瀏覽器 API 呼叫的中央協調者。
• 從 storage 還原持久狀態，不要假設 background script 會永久執行。
• 使用 alarms、明確的事件監聽器與小型功能模組，而不是一條龐大的啟動路徑。

​

常見錯誤

• 把 service worker 當成永久執行的伺服器程序。
• 把關鍵狀態只保存在記憶體裡。
• 在每次事件喚醒時都做沉重的啟動工作。
• 把太多功能邏輯放在 popup 或 content script，但實際上需要的是 background 等級的瀏覽器 API 存取。

​

最佳實務

• 以 MV3 為主的擴充功能優先採用 background.service_worker。
• 讓 background 進入檔案保持小巧，把邏輯委派給共用模組。
• 避免在 service worker 中做沉重的啟動工作；在安全的情況下採用延遲初始化。
• 在開發流程中，把 manifest 中 background 欄位的編輯視為結構性變更。
• 經由通過驗證的訊息處理器來路由特權動作。
• 把持久設定與快取放到瀏覽器 storage，而不是只放在模組層級變數中。

​

後續步驟

• 在 dev 更新行為中了解更新結果。
• 透過 Storage 保存持久的 runtime 狀態。
• 透過 Messaging 協調各情境。
• 進一步了解開發中的 JavaScript。
• 繼續閱讀 content script。
• 在 Manifest V3 疑難排解中排查 service worker 行為。