效能優化能力
快速優化流程
- 在一個目標瀏覽器上測量首次執行行為。
- 縮減 content scripts 與背景處理器中的同步啟動工作。
- 把可選的 UI 功能延後到首次繪製後。
- 重新檢查建置輸出大小,並對關鍵流程做煙霧測試。
Content scripts
- 入口檔保持精簡,延後非關鍵工作。
- 避免在
document_start進行繁重的同步 DOM 掃描。 - 為 observer 與事件監聽器限定範圍;在重新掛載/釋放時清理。
- 把可重用邏輯拆成共用模組,但避免脆弱的動態 import 模式。
背景/service worker
- 啟動時將工作量降到最低;事件到達時再延遲初始化。
- 在安全前提下快取穩定的計算結果。
- 在事件處理器中避免長時間的同步工作。
- 在活躍開發階段留意 service worker 相依套件的變化。
UI 介面(popup/options/新分頁/側欄)
- 保持初始繪製路徑輕量。
- 大型可選 UI 功能按需載入。
- 框架的 dev tools 僅在本機除錯需要時使用。
- 樣式保持模組化,避免大型的全域 CSS。
資產與資源
- 依目標用途優化 icon/圖片大小。
- 把 web-accessible resources(WAR)限制在必要資產。
- 公開資產要有意識地管理;移除已棄置的檔案。
- 定期驗證產生的
dist/<browser>輸出大小。
精簡發佈的內容
dist/<browser> 裡的每一個位元組,都是每位使用者在安裝時和每次更新時要下載的位元組,而 content script 的資產會隨它一起進入每個相符的頁面。下面說明 extension build 已經排除了什麼、剩餘的大小來自哪裡,以及到哪裡讀取這個數字。
建置排除了什麼。 輸出從 manifest.json 出發並沿著參照走。它會發佈 manifest 指名的項目(background、content script、頁面、圖示、locale)、這些項目匯入的模組和資產,以及 public/ 下的全部內容。src/ 裡沒有任何東西參照的檔案不會被輸出。一個筆記檔案、一個未使用的模組、一個 fixture 資料夾,或者圖示旁邊的一張多餘圖片,永遠不會進入 dist/。你不需要為它們準備忽略清單。
public/ 與匯入的資產。 這兩條路徑的行為不同,而這個差異正是多餘位元組的常見來源:
public/會原樣複製到輸出根目錄,連同資料夾結構,並且不做任何檢查。那裡的過期檔案也會被發佈。請把這個資料夾當作你決定要發佈的檔案清單,並修剪它。- 從 JavaScript 匯入的資產會落在
assets/<name>.<hash>.<ext>,只發佈一次,而且只在匯入存在時才發佈。 - 從 HTML 頁面參照的資產會寫兩份:一份在
assets/<relative path>下,一份在它的來源路徑上,這樣指令碼程式碼裡的參照仍然可用。一個既被 HTML 頁面參照又被 JavaScript 匯入的檔案會發佈三份。請從 JavaScript 匯入共用圖片,或者把它移到public/並按根路徑參照,這樣它只會寫一份。
web_accessible_resources 的範圍。 在 Manifest V3 上,建置會在你所有 content script 的 matches 聯集之下,把兩類檔案加入 web_accessible_resources:content script 透過 import() 載入的每個 chunk,以及 assets/ 下每個非指令碼檔案,無論是哪個頁面或指令碼把它放在那裡的。從 public/ 複製的檔案不會被加入。由此有兩個結論。讓 matches 保持在功能允許的最窄範圍。把只給頁面用的圖片放在 assets/ 之外(從 public/ 按根路徑參照它們),這樣 content script 的 matches 就不會暴露它們。請見讓網頁能讀取擴充功能檔案。
讀取大小。 extension build 會印出輸出的樹狀結構及每個檔案的大小,並以總計收尾:
--zip 時,第二行會給出壓縮檔的名字和壓縮後的大小。壓縮檔只包含 dist/<browser> 的內容,別無其他,位於 dist/<name>-<version>-<browser>.zip,其中 name 是 manifest 的 name 轉為小寫並去掉標點:
extension build --output json 會回傳 total_bytes、largest_asset_bytes 以及 zip_artifacts 中每一項的大小,同樣的摘要還會寫到 dist/extension-js/<browser>/build-summary.json。在 CI 裡跨提交比較 total_bytes,就能在商店審核發現之前抓住大小回歸。請見 build。
效能預算
正式建置(build)在 bundle 超出該類別大小預算時會發出 警告。預算在 production 模式預設啟用,預設情況下超出預算只會發出警告。
在
extension.config.js 用 perfBudgets 覆寫任何類別(值為位元組):
perfBudgets 中設定 onExceed: 'error'。這需要 4.1.41 之後的版本。超出預算這時會成為代碼為 E_PERF_BUDGET 的錯誤,建置以 1 結束。沒有這個設定,或設為 onExceed: 'warn' 時,超出預算會以 W_PERF_BUDGET 警告。其他任何 onExceed 值都會讓建置以 E_CONFIG_LOAD 停止。
ignore 讓單一資源不受任何預算約束。依警告印出的方式列出輸出路徑,也就是相對於建置資料夾的路徑。在樣式中,* 匹配單一資料夾內的內容,** 可以跨資料夾。
預算依由弱到強的順序分層:頂層,然後是 browser.<vendor>,然後是 commands.build。從 4.1.41 之後的版本起,只設定一個類別的層會保留其他層設定的類別。較強層中的 ignore 清單會取代較弱層的清單。
警告列出的內容
警告會列出每個超出預算的檔案,最大的排在最前,並給出它的大小、適用的預算與它的角色:and 5 more。
一個 .wasm 檔案可能落入三種預算,所以建議會指出實際適用的那一個:perfBudgets.runtime、perfBudgets.wasm 或 perfBudgets.public。如果這個大小是刻意的,請調高該鍵,或把檔案列入 ignore。
不合法的預算值
從 4.1.41 之後的版本起,正式建置會以代碼E_CONFIG_LOAD 拒絕不合法的 perfBudgets 值。更早的版本會丟棄或誤讀這樣的值,且不給任何訊息。
從 4.2.0 起,dev 會在啟動伺服器之前以 E_CONFIG_LOAD 拒絕同樣的值。被拒絕的 build 還會把之前的 ready.json 標記為失敗。見 ready.json 錯誤狀態。
每則拒絕訊息都會指出設定檔,並給出一個合法的範例。未知鍵的警告會列出可接受的鍵:
content-script、service-worker、page、shared、public、runtime、wasm、ignore 與 onExceed。
預算設為 0 並不會關閉某個類別。要讓某個檔案不受預算約束,請把它列入 ignore。ignore 中的空白字串會被略過。
操作檢查
- 在 CI 中執行多瀏覽器建置檢查。
- 追蹤端對端(E2E)執行時長隨時間的回歸訊號。
- 為關鍵的擴充功能流程加入煙霧測試(安裝、開啟 UI、content script 啟動)。
常見效能陷阱
- 大型 content-script bundle 在每個匹配頁面上載入
- 在
document_start進行繁重的工作而沒有條件守衛 - Service worker 處理器做同步、非必要的初始化
- UI 介面只用到部分功能卻附帶大型全域 CSS/JS
下一步
- 檢視 Playwright E2E。
- 檢視 安全檢查清單。

