dev,享有監看模式、瀏覽器啟動與情境感知的更新行為。
dev 會執行開發管線並監看你的專案檔案。它會依變更內容套用不同的更新策略:Hot Module Replacement (HMR)、硬重新載入,或必要時的完整重啟。
何時使用 dev
- 開發功能並即時驗證變更。
- 在一個或多個瀏覽器目標中除錯擴充功能行為。
- 透過
--source進行原始碼檢視的工作流程。
build,需要正式版建置 + 啟動請用 start,只執行既有建置輸出請用 preview。
如果你的擴充功能放在 monorepo/submodule 中,請了解 extension.config.* 如何載入環境檔案(包含 workspace 根目錄的後備):環境變數。
Dev 指令功能
| 功能 | 你可以得到的能力 |
|---|---|
| 監看模式迭代 | 編寫時保持「編輯 → 重建 → 驗證」緊密迴圈 |
| 瀏覽器目標控制 | 透過明確的指令進行跨瀏覽器驗證 |
| 設定檔感知執行 | 依工作流程需求可靠地選擇全新或持久設定檔 |
| 原始碼檢視模式 | 透過 source 旗標取得結構化輸出與診斷 |
用法
https://github.com/user/repo/tree/main/path)。Extension.js 會下載儲存庫,並對本地副本執行開發模式。
最常用的旗標
這些涵蓋 80% 的情境。其餘可參見 完整參考。| 旗標 | 用途 | 預設值 |
|---|---|---|
--browser <target> | 以 Chrome、Edge、Firefox 為目標,或以逗號分隔列出。 | chromium |
--polyfill | 為 Chromium 目標銜接 browser.* API,以執行 Firefox 風格的原始碼。 | false |
--port <port> | 開發伺服器埠號。設 0 讓作業系統指定。 | 8080 |
--starting-url <url> | 瀏覽器啟動時開啟此 URL。 | 未設 |
--no-reload | 略過自動重新載入。當你想得到乾淨的開發包時使用。 | 啟用 |
引數與旗標
| 旗標 | 別名 | 用途 | 預設值 |
|---|---|---|---|
[path or url] | - | 擴充功能路徑或遠端 URL。 | process.cwd() |
--browser <browser> | -b | 瀏覽器/引擎目標(chromium、chrome、edge、firefox、引擎別名,或逗號分隔的值)。 | chromium |
--profile <path|boolean> | - | 瀏覽器設定檔路徑,或布林模式。 | 全新設定檔 |
--chromium-binary <path> | - | 自訂 Chromium 系列執行檔路徑。 | 系統預設 |
--gecko-binary <path> | --firefox-binary | 自訂 Gecko 系列執行檔路徑。 | 系統預設 |
--polyfill [boolean] | - | 為 Chromium 目標啟用 browser.* API 相容性 polyfill。 | false |
--starting-url <url> | - | 啟動瀏覽器後開啟的 URL。 | 未設 |
--port <port> | - | 開發伺服器埠號。設 0 讓作業系統指定。 | 8080 |
--host <host> | - | 開發伺服器要綁定的主機。Docker/dev container 請用 0.0.0.0。 | 127.0.0.1 |
--no-open | - | 不要自動啟動瀏覽器。 | 預設會啟動瀏覽器 |
--no-browser | - | 不啟動瀏覽器。 | 預設啟動瀏覽器 |
--no-reload | - | 略過 content script 的重新載入執行階段與重建時的 reload dispatch。需手動重新整理分頁才能看到變更。 | 預設啟用 reload runtime |
--wait [boolean] | - | 等待 dist/extension-js/<browser>/ready.json 後結束。 | 停用 |
--wait-timeout <ms> | - | --wait 模式的逾時時間。 | 60000 |
--wait-format <pretty|json> | - | 等待結果的輸出格式(json 為機器可讀)。 | pretty |
--extensions <list> | - | 以逗號分隔的搭配擴充功能或 store URL。 | 未設 |
--install [boolean] | - | 當缺少時安裝專案相依套件。 | 依指令行為而定 |
--author | --author-mode | 啟用維護者診斷。 | 停用 |
自動化中介資料(建議用於腳本/代理)
當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標示執行階段開始時間
--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 之外讀取它。
原始碼檢視工作流程
原始碼選項僅與dev 搭配使用。原始碼檢視會在瀏覽器中開啟目標 URL,並在你的 content script 執行之後印出完整的即時 HTML。可用來驗證擴充功能實際做了哪些改動。
--source [url]檢視一個頁面(預設為--starting-url,否則為https://example.com)--watch-source/--no-watch-source在每次重建時重新印出 HTML
start 與 preview 不支援原始碼檢視旗標。
Source 旗標
| 旗標 | 用途 | 預設行為 |
|---|---|---|
--source [url] | 啟用原始碼檢視流程。 | 停用 |
--watch-source [boolean] | 在監看更新時重新印出原始碼輸出。 | 啟用 --source 時為 true |
--source-format <pretty|json|ndjson> | 原始碼檢視的輸出格式。 | 回退到 log 格式或 json |
--source-summary [boolean] | 發出精簡的摘要輸出。 | 停用 |
--source-meta [boolean] | 包含頁面中介資料。 | 開啟 source 時啟用 |
--source-probe <selectors> | 以逗號分隔的 CSS 選擇器探測。 | 未設 |
--source-tree <off|root-only> | 包含精簡的擴充功能樹狀詳情。 | 未設 |
--source-console [boolean] | 包含 console 摘要。 | 停用 |
--source-dom [boolean] | 包含 DOM 快照/差異。 | 開啟 watch-source 時啟用 |
--source-max-bytes <bytes> | 限制輸出 payload 大小。 | 未設 |
--source-redact <off|safe|strict> | 原始碼輸出的遮蔽策略。 | 依格式決定 |
--source-include-shadow <off|open-only|all> | 控制 Shadow DOM 的包含方式。 | 開啟 source 時為 open-only |
--source-diff [boolean] | 在監看更新時包含 diff 中介資料。 | 開啟 watch-source 時啟用 |
記錄旗標
| 旗標 | 用途 | 預設值 |
|---|---|---|
--logs <off|error|warn|info|debug|trace|all> | 最低記錄等級。 | off |
--log-context <list|all> | 情境過濾(background、content、page、sidebar、popup、options、devtools)。 | all |
--log-format <pretty|json|ndjson> | logger 輸出格式。 | pretty |
--no-log-timestamps | 在 pretty 模式停用時間戳。 | 預設啟用時間戳 |
--no-log-color | 在 pretty 模式停用顏色。 | 預設啟用顏色 |
--log-url <pattern> | 以 URL 子字串/正則過濾記錄事件。 | 未設 |
--log-tab <id> | 以分頁 ID 過濾記錄事件。 | 未設 |
共用全域選項
也支援 全域旗標.Monorepo 與 workspace 根目錄
你可以將dev(以及 build)指向 monorepo 的根目錄,而不是擴充功能套件本身。Extension.js 會偵測 workspace 根目錄並自動解析其中的擴充功能套件:
範例
執行本地擴充功能
從 GitHub 執行遠端擴充功能
將 GitHub 樹狀 URL 當作引數,即可在本機開發遠端擴充功能:使用 source 模式檢視頁面 HTML
在 Firefox 中執行
依序在多個瀏覽器中執行
在 Docker 或 dev container 中執行
當你在 Docker、dev container 或 GitHub Codespaces 中執行時,將開發伺服器綁定到0.0.0.0,主機才連得到:
--port 0 讓作業系統自動挑選可用埠號:
將 Brave 作為自訂執行檔執行
最佳實務
- 瀏覽器相容性: 在不同瀏覽器中測試,確認每個目標都能正常運作。
- 使用 polyfill: 如果 Firefox 或 Gecko 系列瀏覽器也是目標,使用
--polyfill。此旗標會在 Chromium 系列瀏覽器中啟用browser.*API 相容性。 - 原始碼檢視工作流程: 當你需要原始碼檢視時,使用
dev,而非start/preview。 - 自動化可靠性: 把
dev視為監看模式的搭配(--no-browser+dev --wait)。把start視為正式版的搭配(--no-browser+start --wait)。對腳本與 CI 自動化,使用--wait-format=json。
後續步驟
- 用
build產生正式版產物。 - 用
start驗證正式版啟動流程。 - 透過 瀏覽器專屬 manifest 欄位 了解瀏覽器目標。
- 在
extension.config.js中集中設定共用預設值。 - 在 環境變數 中了解設定的環境檔載入行為。