用於監看模式與即時重新載入的 Dev 指令

​

何時使用 dev

• 開發功能並即時驗證變更。
• 在一個或多個瀏覽器目標中除錯擴充功能行為。

​

Dev 指令功能

​

用法

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

extension dev [path-or-url] [options]

​

最常用的旗標

​

引數與旗標

• --wait-format <pretty|json> 會對應到 --output,並在 stderr 警告一次。請把腳本遷移到 --output。
• --author 與 --author-mode 會對應到 --debug。

​

Safari 旗標

​

父程序看門狗

​

埠號如何決定

​

自動化中介資料(建議用於腳本/代理)

• dist/extension-js/<browser>/ready.json
• dist/extension-js/<browser>/events.ndjson(以換行分隔的 JSON)

• 啟動中:status: "starting"
• 建置編譯完成:status: "ready"
• 啟動/編譯失敗:status: "error",瀏覽器根本沒有啟動(code: "browser_launch_failed")或在擴充功能載入之前就結束(code: "browser_exited")時也是
• 工作階段關閉後:status: "stopped",因此已經死掉的工作階段不會再宣稱自己 ready
• service worker 連上之後為 runtime: "attached"(並附上 executorAttachedAt)。act verb 應該等待它,而不是等待 ready
• 從 4.1.20 起,最後一個已連線的擴充功能情境斷線後為 runtime: "detached"(並附上 executorDetachedAt)。executorAttachedAt 會作為來源記錄保留,重新連線後該值會回到 "attached"
• runId 唯一識別一次執行階段工作階段
• startedAt 標示執行階段開始時間
• command 記錄產生它的指令(dev、start、preview 或 build)
• toolchainVersion、extensionName 與 extensionVersion 記錄是哪個 Extension.js 版本、為哪個擴充功能產出了這棵目錄樹——終端機捲動紀錄消失後,這個檔案仍是一份建置回執
• port 是實際綁定的開發伺服器埠號,host 則是用戶端可以撥號的可連線主機(參見綁定主機與可連線主機)
• controlPort / instanceId 定位 extension logs 與 act verb 使用的控制橋
• cdpPort(Chromium)與 rdpPort(Gecko)公開瀏覽器的除錯埠號
• profilePath、browserPid 與 extensionId 由瀏覽器啟動器在啟動後寫入

​

阻止瀏覽器啟動

# 阻止瀏覽器啟動。開發伺服器繼續執行。
extension dev --no-browser

# 啟動瀏覽器,但不為擴充功能開啟分頁。
extension dev --no-open

​

--no-browser 與就緒同步

• content script 的變更會就地重新注入到已開啟的相符分頁(service worker 會用最新建置執行 chrome.scripting.executeScript),所以存檔後頁面就會更新,不需手動重新整理。之後才開啟的分頁也會拿到新的建置,因為 service worker 會動態重新註冊 content script(chrome.scripting.registerContentScripts)。
• service worker / manifest 的變更會重啟擴充功能。

1. 以長駐程序執行 extension dev --no-browser。
2. 用 extension dev --wait --browser=<browser> 作為就緒閘道。
3. 只在 status: "ready" 後才啟動外部瀏覽器自動化。

​

用 --output json 取得機器輸出

• 一般的 dev 執行會在工作階段建立之後、緊接在 starting 訊框之前,把一個 status: "started" 訊框當作 stdout 的第一行印出。它帶有專案路徑、瀏覽器清單、請求的埠號,以及開發伺服器的 pid。dev 不會自行結束,所以後面不會再有結果訊框。接下來的 生命週期訊框(starting、compiled、ready 以及之後的訊框)同樣寫到 stdout,給人看的進度行則寫到 stderr,因此 stdout 的每一行都能以 JSON 解析。即時狀態請讀 ready.json。
• 在工作階段建立之前就被拒絕的執行只會印出一個 ok: false 訊框,前面沒有 started 訊框。這包括缺少 manifest(E_MANIFEST_NOT_FOUND)、manifest 無法解析(E_MANIFEST_INVALID)、設定檔載入失敗(E_CONFIG_LOAD),以及遠端 URL 沒有提供可用的封存檔(E_REMOTE_ZIP_INVALID、E_REMOTE_FETCH_TIMEOUT 或 E_REMOTE_DOWNLOAD)。
• --chromium-binary 或 --gecko-binary 固定的執行檔有問題時,伺服器不會停止。這包括路徑不存在、檔案無法執行,以及執行檔在 10 秒內沒有回應版本探測。契約會進入 error,代碼為 browser_launch_failed,並帶 browserLaunchFailedCode: "E_BROWSER_BINARY_INVALID"。失敗訊框帶著該 readyCode,其中 status: "usage",error.code: "E_BROWSER_BINARY_INVALID",對該工作階段執行的 dev --wait 也會以同樣的狀態與代碼回應。
• 固定的執行檔可以執行但系統無法啟動它時,伺服器同樣保持運作。失敗訊框的 status: "failed",error.code: "E_READY_ERROR_STATUS",readyCode 為 browser_launch_failed。
• dev --wait 成功時會印出一個 status: "ready" 訊框。它的 value.results 陣列會逐一瀏覽器帶出完整的就緒契約。
• 失敗時會在程序以 1 結束前,印出一個帶有 error.code(例如 E_READY_TIMEOUT)的 ok: false 訊框。處於 error 狀態的契約會指明原因:固定的執行檔遭拒時是帶 status: "usage" 的 E_BROWSER_BINARY_INVALID,瀏覽器根本沒有啟動時是 E_BROWSER_LAUNCH,在擴充功能載入之前就結束時是 E_BROWSER_EXITED,編譯錯誤是 E_COMPILE。完整清單見 ready.json 契約。

​

用 --no-reload 取得乾淨的開發包

​

記錄旗標

​

共用全域選項

​

Monorepo 與 workspace 根目錄

extension dev .            # run from the monorepo root

Workspace root detected — resolved extension package: packages/my-extension

extension dev packages/my-extension

​

pnpm workspace 成員從根目錄安裝

pnpm install --filter {packages/my-extension}...

This project is a pnpm workspace member, installing from the workspace root at /home/dev/monorepo.

​

範例

​

執行本地擴充功能

extension dev ./my-extension

extension dev ./my-extension

extension dev ./my-extension

extension dev ./my-extension

extension dev ./my-extension

​

從 GitHub 執行遠端擴充功能

extension dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder

extension dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder

extension dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder

extension dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder

extension dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder

​

在 Firefox 中執行

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

extension dev ./my-extension --browser firefox

​

依序在多個瀏覽器中執行

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

extension dev ./my-extension --browser=chrome,firefox

​

在 Docker 或 dev container 中執行

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

extension dev ./my-extension --host 0.0.0.0 --port 0

​

綁定主機與可連線主機

• --host 0.0.0.0 會綁定所有網路介面,但 0.0.0.0 並不是可連線的位址。Extension.js 會自動改為向瀏覽器公告 127.0.0.1,這正是常見的埠號轉發式 Docker/dev container/Codespaces 設定所需要的目標:瀏覽器跑在主機上,埠號被轉發進容器。
• 對於真正的遠端設定(瀏覽器與開發伺服器不在同一台機器上),請用 --public-host 傳入瀏覽器連得到的位址(區網 IP 或主機名稱)。它會被傳播到 HMR 用戶端 URL、ready.json,以及烘焙進擴充功能裡的重新載入橋接。

# Browser on another machine reaches the dev server at devbox.local
extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

extension dev ./my-extension --host 0.0.0.0 --public-host devbox.local

extension dev ./my-extension --host 0.0.0.0 --allowed-hosts web,.ngrok.app

​

將 Brave 作為自訂執行檔執行

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

extension dev ./my-extension --chromium-binary /path/to/brave

​

最佳實務

• 瀏覽器相容性: 在不同瀏覽器中測試,確認每個目標都能正常運作。
• 使用 polyfill: dev 中 polyfill 預設開啟,所以 browser.* 呼叫在 Chromium 系列瀏覽器中也能運作。想要未經處理的原始打包時,請傳入 --no-polyfill。
• 自動化可靠性: 把 dev 視為監看模式的搭配(--no-browser + dev --wait)。把 start 視為正式版的搭配(--no-browser + start --wait)。對腳本與 CI 自動化,使用 --output=json。

​

後續步驟

• 用 build 產生正式版產物。
• 用 start 驗證正式版啟動流程。
• 透過 瀏覽器專屬 manifest 欄位 了解瀏覽器目標。
• 在 extension.config.js 中集中設定共用預設值。
• 在 環境變數 中了解設定的環境檔載入行為。