跳轉到主要內容
每次檔案變更使用最輕量的更新策略,讓開發節奏快速。 每次檔案變更後想要快速回饋?Extension.js 會自動選擇最安全、最快速的更新路徑:
  • HMR(hot module replacement):當模組更新是安全的時候
  • 分類重載(full、service worker、content scripts,或僅通知的 page):當執行階段資產有變更時
  • 編譯器自動重新啟動:當 entry 結構有變更時

重新載入前置條件(devtools 設定對話框)

在評估重新載入行為之前,先確認 Extension.js devtools 的 Confirm setup 對話框所列的相同設定檢查: 如果你跳過任一步驟,即使建置流水線健康,重新載入行為也可能看起來不一致。

重新載入層級

1) Hot module replacement(最快路徑)

當程式碼可以更新而不需重啟擴充功能的背景程序與事件監聽器時,Extension.js 會使用 HMR。 常見例子:
  • 附加在擴充功能 HTML 頁面上的腳本(透過注入的 HMR 包裝接受更新)
  • 非 service worker 流程中的背景腳本模組
  • 透過 userScripts API 註冊的腳本
  • 在支援的 content-script/runtime 包裝中的 CSS 更新
從 4.1.41 之後的版本起,頁面的熱更新程式碼只會放進頁面引用的指令碼。當 React、Vue 或 Svelte 負責重新整理時,不會加入這段程式碼。

2) 分類重載

當一次變更需要的不只是 HMR 時,Extension.js 會把它歸入四種重載類型其中之一: 這個判定來自編譯器的 chunk 圖,而不是檔名,並遵循固定順序:
  1. 強制 full。 對 manifest.json 或 _locales/ 底下任何內容的變更,一律歸類為 full,不論還改了什麼。
  2. Chunk 歸屬。 Extension.js 會查出每個變更來源檔屬於哪些 chunk。位於 background/ chunk 的來源檔代表 service-worker,位於 content_scripts/ chunk 的來源檔代表 content-scripts。
  3. 變更的靜態資產。 有些變更檔案存在於輸出目錄,卻不屬於任何 chunk:圖示、web-accessible 資源、DNR 規則集。它們會強制 full,讓瀏覽器從磁碟重新讀取。
  4. 名稱啟發式。 僅用於 chunk 圖不認識的來源檔:路徑符合 background 或 service worker 樣式的歸類為 service-worker。
  5. Content 後備。 若 manifest 宣告了 content script,其餘未知的變更會重新注入每一個 content-script entry。
  6. 僅通知的 page。 其他一切都是 page 指令:重新整理由 livereload 負責,重載通告仍會發出。
同時存在於 service-worker chunk 與 content-script chunk 的來源檔會向兩條路徑扇出。一次儲存會觸發 SW 重新啟動,並在同一份分類指令中帶上待重新注入的過期 content-script entry。 每次開發階段的重載都會由開發伺服器產生單一的情境標籤來通告。格式是 context (fileA, fileB +2 more),例如 service_worker + content_script (shared/api.ts)。同一個標籤會原封不動出現在 CLI 的 stdout、頁面 devtools 主控台與 devtools 標籤中,讓你不必猜測就能在三處對應同一次重載。
如果瀏覽器在重載後仍提供過期的快取 service worker,開發伺服器會偵測到版本不一致並自動重新同步擴充功能。你不需要手動移除再重新加入擴充功能才能恢復。 full 或 service-worker 重載會重新啟動擴充功能。如果擴充功能確認了這次重載,卻沒有在 15 秒內重新連線,dev 工作階段會印出一則警告。這一行會說擴充功能 has not come back since, so this edit may not be live。請在瀏覽器裡重新載入擴充功能。需要 4.1.39 之後的版本。 重新啟動得慢不等於重新啟動失敗。如果擴充功能在這則警告之後重新連上,工作階段會再印出一行。is back after 22s, so this edit is live. Nothing to reload. 表示 worker 執行的是目前的建置。如果 worker 回來時執行的是更早的建置,這一行會說這次修改沒有生效,並請你在瀏覽器裡重新載入擴充功能。
為什麼開發階段的 content script 檔名會包含雜湊? Chrome 會積極快取 chrome-extension:// 資源。像 content-0.js 這種穩定檔名即使在完整擴充功能重載後仍可能提供舊的程式碼。Extension.js 會在開發時加上短雜湊(例如 content-0.abcd1234.js),每次重建都會產生新的 URL 來繞過快取。正式建置則使用乾淨的名稱。在 extension.config.* 的 commands.dev 底下設定 hashContentScripts: false 可以停用它,保留穩定的開發階段檔名。同名的頂層鍵會被忽略。

3) 編譯器重新啟動(開發伺服器)

當擴充功能的 entrypoint 引用變更(不僅是模組內容)時,dev 工作階段會自行重新啟動編譯器並重新載入擴充功能。你不需要重新啟動指令。 工作階段會為這些變更重新啟動:
  • manifest 的修改新增、移除或重新命名了指令碼、頁面、圖示或 JSON 進入點
  • HTML entrypoint 的腳本或樣式引用變更
  • 在 pages/ 或 scripts/ 下新增了檔案
  • .env 檔案變更
從 4.1.41 之後的版本開始,在 pages/ 或 scripts/ 下刪除或重新命名檔案時,以及指令碼移到另一個 manifest 鍵時,工作階段也會重新啟動。重新啟動會移除已不存在的進入點的輸出。 從 4.1.41 之後的版本起,啟動時缺少的頁面指令碼或樣式表被建立後,工作階段也會重新啟動。執行中的工作階段會自行重新啟動。 只有一種變更仍然需要你來重新啟動:編輯 extension.config.*。工作階段會繼續使用啟動時讀到的設定,並印出一則警告。請停止工作階段,重新執行 extension dev。

行為矩陣

Safari

上面的層級是 Chromium 與 Gecko 的重新載入路徑。從 4.1.20 起,Safari 的 dev 工作階段走另一條路:每次儲存會重建 dist/safari,以一次增量 xcodebuild 同步 app 的資源,並在 Safari 中重新載入擴充功能。在 Safari 26.5.2 上量測,從儲存到擴充功能完成重新載入大約 4 秒,沒有 HMR 這一層。請見 建置 Safari 擴充功能。

開發階段的 runtime 如何注入

重載外掛會以五個注入步驟為你的建置加裝,然後進行清理:
  1. 從無法承載開發伺服器 runtime 的 content-script chunk 中移除該 runtime。
  2. 在 background 與 content-script entry 上設定重載策略。
  3. 注入 service worker 的腳本重播 shim,讓 /scripts/* 的注入在編輯後重新執行。
  4. 注入 bridge producer,讓 background 把主控台輸出轉送到控制通道。
  5. 注入 bridge relay,讓 content-script 的主控台輸出抵達同一個通道。
之後會有一個清理步驟管理 hot/。熱更新 chunk 是從擴充功能來源上的磁碟取得的,所以過期的世代會在最終產物中累積。Extension.js 會保留目前世代與前一個世代(供進行中的請求使用),並在每次編譯後刪除其餘的。 整條流程僅限開發階段。在正式建置中,以及當你傳入 --no-reload 時,它不會做任何事。

重新載入 manifest 外的腳本與 HTML

pages/ 與 scripts/ 採用與 manifest 宣告資產相同的重新載入策略。
  • 既有的模組更新可以使用熱更新路徑。
  • Entrypoint 集合變更(新增/刪除或引用圖變更)會讓工作階段重新啟動編譯器。
範例:
Extension.js 會把 /pages 與 /scripts 資料夾辨識為可熱重載的位置,並把 每個 entry 視為可以獨立重載的頁面或腳本。
從 /scripts/* 中以 chrome.scripting.executeScript 動態注入的腳本,在編輯時會被 重播。當你修改 /scripts/ 下的檔案時,Extension.js 會在同一個分頁重新執行相同的注入, 並先卸載前一次的掛載——所以動態注入的腳本可以即時更新,效果就像宣告式的 content_scripts 一樣,而不會留下過期的 DOM 直到你手動重新觸發。這是一項僅限開發階段 的便利設計。
從 4.1.39 之後的版本起,重播在 Firefox 上也生效。修改一個用 scripting.executeScript 注入的檔案後,新的內容會在已開啟的分頁裡執行。這次修改沒有重新載入任何頁面時,終端機會說明:

瀏覽器主控台裡的內容

從 4.2.0 之後的版本起,dev 執行環境在瀏覽器主控台中為失敗或警告印出的行,會以 錯誤碼表 中的一個代碼開頭:
  • W_RELOAD_NOT_APPLIED:重新載入或熱更新沒有生效,所以開啟的頁面或擴充功能保留它已有的建置。
  • W_CONTENT_SCRIPT_NOT_INJECTED:出現在背景主控台,背景無法回應要求其 content script 的頁面,所以該頁面在沒有它的情況下執行。
  • W_DEV_SERVER_SOCKET:某個擴充功能頁面失去與開發伺服器的 socket,所以修改要在頁面重新載入後才顯示。
  • W_CONTENT_SCRIPT_CLEANUP:出現在頁面主控台,content script 回傳的清理函式擲出錯誤,所以指令稿留在頁面上的內容可能會保留。
  • W_CONTENT_SCRIPT_MOUNT:出現在頁面主控台,content script 的預設匯出在執行時擲出錯誤。
只用於告知的行,例如 [Extension.js] Reloading <label>…,不帶代碼。4.2.0 及之前的版本把這些失敗印為 Extension.js: <text>,不帶代碼。

最佳實務

  • 在進行中的開發階段保持 entrypoint 引用穩定,以最大化 HMR。
  • 把 manifest.json 與語系編輯批次進行,避免反覆觸發整個擴充功能重載。
  • 用 pages/ 與 scripts/ 放置 manifest 之外的資產。
  • 把需要重啟的診斷視為刻意的安全檢查,而不是短暫的警告。

下一步