跳轉到主要內容
Brave
Chrome
Extension.js
Edge
Safari
Opera
Firefox
Chromium
Waterfox

跨瀏覽器擴充功能框架

用一套現代工作流程,為所有主流瀏覽器打造擴充功能。Extension.js 會處理 manifest 編譯、瀏覽器專屬的輸出與封裝。

GitHub starsnpm weekly downloadslatest version on npmMIT license
npx extension@latest create my-extension

一份 manifest.json。
支援所有瀏覽器。

帶有瀏覽器前綴的鍵(chrome:、firefox:、 edge:、safari:)會在編譯時過濾,未加前綴的鍵則對所有瀏覽器都生效。


  “manifest_version”: 3,
  “name”: “My Extension”,
  “version”: “1.0.0”,
  “action”:  “default_popup”: “popup.html” ,
  “chromium:background”:  “service_worker”: “sw.ts” ,
  “firefox:background”:  “scripts”: [“sw.ts”] 
Extension.js

為什麼要使用瀏覽器擴充功能框架?

瀏覽器擴充功能會用到與一般 web app 不同的檔案、瀏覽器 API、manifest 格式、權限與建置輸出。 一個 瀏覽器擴充功能框架 能去除那些黏合用的程式碼:以單一工作流程處理 Chrome、Edge、Firefox 與 Safari 的擴充功能開發、依目標過濾 manifest、針對 service worker 與 content script 調校的重新載入行為,以及為 Chrome Web Store、addons.mozilla.org 與 Edge Add-ons store 準備好的封裝。

Extension.js 就是這樣的工作流程:一個 JavaScript 或 TypeScript 專案、一份 manifest.json、分開的 dist/<browser> 輸出,以及一個不擋路的 CLI,讓你能毫不費力地以同一份程式碼推出跨瀏覽器擴充功能。

看看完整的開發者工作流程

從建立專案骨架到擴充功能執行,全程使用一套現代工具鏈。

涵蓋 擴充功能完整生命週期 的核心功能

用一套現代擴充功能工作流程,為每個瀏覽器建置、測試與發佈。

選擇你的 框架,沿用相同工作流程。

從可上線的範本開始:React、Preact、Vue、Svelte、TypeScript 或 JavaScript。

從其他框架轉過來?

大多數 React、Vue 與 Svelte 的原始檔可以直接搬過來,不必重寫。實際工作集中在替換打包工具設定,並把產生的 manifest 還原為真正的 manifest.json。

支援開源核心

贊助者協助專案推出更快的版本、更好的開發者體驗(DX),並為擴充功能團隊提供長期穩定性。

文件由MintlifyMintlify透過其開源計畫託管。

成為贊助者 ⏵

常見問題

瀏覽器擴充功能是一種為 Chrome、Firefox、Edge、Safari 或其他瀏覽器加入功能的軟體。它可以注入 UI、回應瀏覽器事件,並呼叫頁面本身無法使用的特權 API。完整介紹請見 什麼是瀏覽器擴充功能?。
是的。Extension.js 可作為 Chrome 擴充功能框架,同時也能在同一份專案中作為 Firefox、Edge 與 Safari 的擴充功能框架。透過 --browser=chrome、--browser=firefox、--browser=edge,或 macOS 上的 --browser=safari 選擇目標。請見 可用的瀏覽器。
執行 npx extension dev 後,CLI 會監看你的專案變動。對 popup、content script、service worker 與 options 頁面的編輯會觸發最快且安全的更新路徑。CLI 在支援時使用 hot module replacement(HMR),否則就採用針對性的重新載入。它會自動解決常見痛點,例如過期的 service worker 與遺漏的 content script 更新。
Extension.js 會把單一程式碼庫編譯成各瀏覽器專屬輸出。同一組指令會為 Chrome、Edge、Firefox,以及其他 Chromium 系瀏覽器產生正確封裝的建置。每個建置都會取得正確的 manifest 格式、路徑與平台調整。在 macOS 上,同一個建置指令也會透過 Xcode 產出 Safari 應用程式。你的持續整合(CI)pipeline 可以用相同的建置步驟搭配不同的瀏覽器旗標。這能減少不同上架平台之間的差異。
可以。Extension.js 提供 React、Preact、Vue、Svelte、TypeScript 與純 JavaScript 的正式上線範本。元件的寫法與你在任何前端專案中一樣。框架選擇不會影響核心工作流程。
是的。整套工具鏈是圍繞 Manifest V3 與目前瀏覽器商店強制的限制設計的:service worker、宣告式 API、新版權限與更嚴格的封裝。Manifest V3(MV3)是預設,不是事後追加的。常見陷阱請見 Manifest V3 疑難排解。
大多數 Manifest V3 的問題可分為幾類:service worker 註冊與 type: "module"、新的 web_accessible_resources 結構、permissions 與 host_permissions 的拆分,以及 Firefox 在 declarative_net_request 上的差異。修正方式請見 Manifest V3 疑難排解。
Extension.js 會替換掉手刻 bundler 設定中那些擴充功能專屬的黏合程式碼。它會處理 manifest 版本、多瀏覽器輸出、content script 注入與重新載入協調。將你的原始檔與 manifest 放進 Extension.js 專案,CLI 會處理其餘部分。你的 React/Vue/Svelte/TS 程式碼不需重寫即可運作。
Extension.js 支援 pnpm、npm 與 Yarn workspace。路徑解析與共用相依套件能跨 workspace 邊界運作。Extension.js 會依瀏覽器與建置模式注入環境變數,並在 JS、JSON 與 HTML 中替換值。開發期密鑰絕對不會洩漏到正式 bundle 中。
可以。Extension.js 採用 MIT 授權 的開放原始碼。沒有付費方案、使用上限或必須開啟 telemetry 的模式。本框架由贊助者與貢獻者支持。資料形狀的明確規範請見 telemetry 與隱私契約。
支援。--browser=safari 可用於 macOS 上的 build 與 dev:Extension.js 會用 Xcode 的 safari-web-extension-converter 轉換你的擴充功能,建置並簽章一個 app,然後開啟它。你只需要在 Safari 設定中啟用一次擴充功能,之後 extension logs 會串流 background 與 content 的記錄列,而且每次儲存都會重新載入。它需要完整的 Xcode、僅限 macOS,而且 preview 與 start 沒有 Safari 路徑。請見 建置 Safari 擴充功能。
正式建置(extension build)只會輸出你的擴充功能參照到的程式碼。reload 與 HMR 的連結邏輯僅存在於開發建置,正式輸出中並不包含。輸出位於 dist/<browser> 之下,方便你比較各瀏覽器的大小。Content script 的 bundle 大小,會接近你的原始碼加上所選 UI 框架的水準。
大多數 React、Vue 與 Svelte 的原始檔可以直接搬過來,不必重寫。工作集中在三個地方:替換打包工具設定、把產生的 manifest 還原為手寫且支援 瀏覽器前綴鍵 的 manifest.json,以及更新 package.json 的 scripts。逐步指南請見 從 CRXJS 遷移。