dev,享有監看模式、瀏覽器啟動與情境感知的更新行為。
dev 會執行開發管線並監看你的專案檔案。它會依變更內容套用不同的更新策略:Hot Module Replacement (HMR)、硬重新載入,或必要時的完整重啟。
何時使用 dev
- 開發功能並即時驗證變更。
- 在一個或多個瀏覽器目標中除錯擴充功能行為。
build,需要正式版建置 + 啟動請用 start,只執行既有建置輸出請用 preview。
如果你的擴充功能放在 monorepo/submodule 中,請了解 extension.config.* 如何載入環境檔案(包含 workspace 根目錄的後備):環境變數。
Dev 指令功能
用法
https://github.com/user/repo/tree/main/path)。Extension.js 會下載儲存庫,並對本地副本執行開發模式。
最常用的旗標
這些涵蓋 80% 的情境。其餘可參見 完整參考。引數與旗標
自動化中介資料(建議用於腳本/代理)
當dev 執行時,Extension.js 會發出機器可讀的中介資料於:
dist/extension-js/<browser>/ready.jsondist/extension-js/<browser>/events.ndjson(以換行分隔的 JSON)
ready.json 視為就緒契約:
- 啟動中:
status: "starting" - 執行階段就緒:
status: "ready" - 啟動/編譯失敗:
status: "error" runId唯一識別一次執行階段工作階段startedAt標示執行階段開始時間command記錄產生它的指令(dev、start、preview或build)toolchainVersion、extensionName與extensionVersion記錄是哪個 Extension.js 版本、為哪個擴充功能產出了這棵目錄樹——終端機捲動紀錄消失後,這個檔案仍是一份建置回執controlPort/instanceId定位extension logs與 act verb 使用的控制橋
events.ndjson 只屬於目前這次執行:新一次執行開始時檔案會重設,且每筆記錄都蓋上本次執行的 runId(與 ready.json 一致),消費端不會看到上一個工作階段的事件與目前的交錯。
工作階段行為異常時,執行 extension doctor——它依序檢查契約、控制通道、權杖、執行器與瀏覽器,並指出第一個失敗的環節與修復方式。
--no-browser 與就緒同步
--no-browser 只會關閉瀏覽器啟動。它不會在編譯完成前阻擋外部 runner。
對 Playwright/CI/AI 工作流程:
- 以長駐程序執行
extension dev --no-browser。 - 用
extension dev --wait --browser=<browser>作為就緒閘道。 - 只在
status: "ready"後才啟動外部瀏覽器自動化。
--wait 是為第二個程序(或 CI 步驟)而設,並在 error/逾時時以非零碼結束。
當 --wait 看到死掉程序(pid 已不存在)留下的過期 ready.json 時,它會持續等待一個仍在運作的產生者。
如果你在同一次指令中同時傳入 --wait 與 --no-browser,--wait 優先,指令會以「僅等待」模式執行。
用 --no-reload 取得乾淨的開發包
--no-reload 會略過 content script 的重新注入包裝,以及重建時的 reload dispatch。開發版的 dist 會更接近正式版打包,並且當檔案變更時不會擾動已開啟的分頁。請自行重新載入擴充功能或頁面以套用變更。
--no-reload 只在 extension dev 支援。把它傳給 start、preview 或 build 會以錯誤結束。它在內部會設定 EXTENSION_NO_RELOAD=true,讓 develop 程序能從 CLI argv 之外讀取它。
記錄旗標
共用全域選項
也支援 全域旗標.Monorepo 與 workspace 根目錄
你可以將dev(以及 build)指向 monorepo 的根目錄,而不是擴充功能套件本身。Extension.js 會偵測 workspace 根目錄並自動解析其中的擴充功能套件:
範例
執行本地擴充功能
從 GitHub 執行遠端擴充功能
將 GitHub 樹狀 URL 當作引數,即可在本機開發遠端擴充功能:在 Firefox 中執行
依序在多個瀏覽器中執行
在 Docker 或 dev container 中執行
當你在 Docker、dev container 或 GitHub Codespaces 中執行時,將開發伺服器綁定到0.0.0.0,主機才連得到:
--port 0 讓作業系統自動挑選可用埠號:
將 Brave 作為自訂執行檔執行
最佳實務
- 瀏覽器相容性: 在不同瀏覽器中測試,確認每個目標都能正常運作。
- 使用 polyfill: 如果 Firefox 或 Gecko 系列瀏覽器也是目標,使用
--polyfill。此旗標會在 Chromium 系列瀏覽器中啟用browser.*API 相容性。 - 自動化可靠性: 把
dev視為監看模式的搭配(--no-browser+dev --wait)。把start視為正式版的搭配(--no-browser+start --wait)。對腳本與 CI 自動化,使用--wait-format=json。
後續步驟
- 用
build產生正式版產物。 - 用
start驗證正式版啟動流程。 - 透過 瀏覽器專屬 manifest 欄位 了解瀏覽器目標。
- 在
extension.config.js中集中設定共用預設值。 - 在 環境變數 中了解設定的環境檔載入行為。