dev,享有監看模式、瀏覽器啟動與情境感知的更新行為。
dev 會執行開發管線並監看你的專案檔案。它會依變更內容套用不同的更新策略:Hot Module Replacement (HMR)、硬重新載入,或必要時的完整重啟。
何時使用 dev
- 開發功能並即時驗證變更。
- 在一個或多個瀏覽器目標中除錯擴充功能行為。
build,需要正式版建置 + 啟動請用 start,只執行既有建置輸出請用 preview。
如果你的擴充功能放在 monorepo/submodule 中,請了解 extension.config.* 如何載入環境檔案(包含 workspace 根目錄的後備):環境變數。
Dev 指令功能
什麼會觸發重新建置
watcher 跟隨建置圖:manifest 與它點名的一切、每個進入點與其 import、pages/、scripts/ 與 public/ 資料夾、_locales/,以及專案設定與 env 檔。專案中其他任何位置的寫入,例如 store/ 底下的一張截圖、一個示範頁面、一份 README 或一個測試 fixture,都不會重新建置或重新載入擴充功能。在 dev 執行期間新建的特殊資料夾會在下一次編譯時被納入。
從 4.1.39 之後的版本起,位於符號連結資料夾下的專案只依一個路徑被監看。在 macOS 上,第一次建置會在有限的時間內等待 watcher 完成首次掃描,然後才回報就緒,這樣過早的儲存不會被漏掉。
從 4.1.41 之後的版本起,建置有錯誤時,儲存仍會重新建置頁面。這包括頁面本身以及它引用的每個檔案。修正錯誤的那次儲存會更新頁面。dev 也會為新的語系資料夾、messages.json 旁的新檔案以及新的 _locales 資料夾重新建置。
從 4.1.41 之後的版本起,指向不存在檔案的 CSS url() 或 require() 會被監看,因此建立該檔案就會重新建置工作階段。在 macOS 上,加入 public/ 的檔案在整個工作階段中都會發布。較早的版本在掃描進行中又觸發重新掃描之後,可能不再發布新的 public/ 檔案。
從 4.1.41 之後的版本開始,編譯器的重新啟動還會清理輸出:
- 當 manifest 的修改移除了一個進入點時,重新啟動會把該進入點的檔案從
dist/<browser>中移除。 - 在
pages/或scripts/下刪除或重新命名檔案,會讓編譯器自行重新啟動,新增檔案時本來就會這樣。重新啟動會移除已不存在的檔案的輸出。你不需要重新啟動指令。
用法
CLI 不是全域安裝的。
npx extension@latest dev 會下載目前版本並執行它,所以單獨的
extension 在你的 shell 裡不是一個指令。在 create 建立的專案裡,npm run dev
會透過 package.json 的 dev 指令碼執行同一個指令。https://github.com/user/repo/tree/main/path)。Extension.js 會下載儲存庫,並對本地副本執行開發模式。
最常用的旗標
這些涵蓋 80% 的情境。其餘可參見 完整參考。引數與旗標
在 Firefox 上,
--starting-url 會在附加元件安裝完成後才開啟,所以你的 document_start content script 會在該頁面上執行。從 4.1.39 之後的版本起,它不再取代你的擴充功能自己開啟的分頁。
有兩個已淘汰的別名雖然從 --help 中隱藏,但仍可運作:
--wait-format <pretty|json>會對應到--output,並在 stderr 警告一次。請把腳本遷移到--output。--author與--author-mode會對應到--debug。
Safari 旗標
這些旗標只適用於safari 與 webkit-based 目標。與其他目標一起傳入其中任何一個都會以 E_INVALID_OPTION 結束,所以打錯字不會靜默地失效。
對 Safari 目標,
dev 還會在第一次打包前執行工具鏈預檢。缺少 Xcode 會以 E_SAFARI_TOOLCHAIN 快速失敗。
從 4.1.20 起,Safari 工作階段就是一個完整的 dev 工作階段。你在 Safari 設定中啟用擴充功能之後,extension logs 可以讀取它,控制通道會接上,而且每次儲存都會在 Safari 中重新載入擴充功能。請見 建置 Safari 擴充功能。
模擬的 Chromium
從 4.1.38 起,--browser=chromium-emulator 會在一個網頁裡的模擬 Chromium 中執行你的擴充功能,不需要設定任何旗標或環境變數。dev 會輸出這個頁面的位址,並在你的預設瀏覽器中開啟它。這個頁面從你本機的開發伺服器讀取建置,所以只有 dev 能開啟這個目標,start 與 preview 會拒絕它。
開啟頁面之前,dev 會先檢查引擎的來源(origin)是否有回應。來源沒有回應時,dev 會輸出一則警告,而且什麼都不開啟:
--logs 對這個目標沒有作用:擴充功能在網頁中執行,所以請在那個頁面上用你瀏覽器的開發者工具讀取它的主控台。
父程序看門狗
--parent-pid 是給衍生 dev 的 harness 與代理使用的,宿主當掉不會外洩伺服器。它的值必須是正整數,其他任何值都會以 E_INVALID_OPTION 結束。看門狗每 2 秒輪詢一次父程序。父程序消失後,dev 伺服器會透過 SIGTERM 關閉;如果清理卡住,還有 5 秒的強制結束後備。
埠號如何決定
--port 是一個請求,不是保證。當請求的埠號被占用時,開發伺服器會往上找最近的空閒埠號。--port 0 會向作業系統要一個任意空閒埠號。請從 ready.json 讀取實際綁定的埠號,而不是你傳入的那個旗標。
--port 只設定開發伺服器的埠號。控制橋監聽它自己的埠號,沒有任何旗標能設定它。第一次執行時,工作階段向作業系統要一個空閒埠號,並把它存進 .extension-js/control-port-<browser>。下一次執行會請求同一個埠號,這樣仍然記著舊埠號的瀏覽器設定檔可以重新連上。這個埠號被占用時,作業系統會另外分配一個。請從 ready.json 的 controlPort 讀取它。
dev 替你的擴充功能加了什麼
dev 工作階段會給自己授予重新載入所需的東西,而同一份原始碼的正式建置裡完全沒有這些。從 4.1.39 之後的版本起,工作階段會在身分卡片下方寫明每一項:
Dev only列列出只有 dev manifest 才有的權限、主機存取或 web accessible 資源。- 從 4.2.0 之後的版本起,以
manifest開頭的Dev only列列出 dev 建置改動過、而正式建置沒有的其他 manifest 欄位,例如content_security_policy 'unsafe-eval'、externally_connectable.ids *或background.persistent true。 - 從 4.2.0 之後的版本起,當 dev manifest 為每個 content script 寫入一個 stub,並由背景 worker 註冊真正的檔案以便修改能到達頁面時,Chromium 工作階段會印出
Dev onlymanifest content_scripts.js dev stubs。isolated world 中的document_start群組保留它的靜態項目。Firefox 沒有 stub,也不會印出這一列。 Dev flag列寫明一個會改變你所見內容的啟動旗標,以及能把它反過來的設定鍵。Dev pref列寫明工作階段寫進一個比工作階段活得更久的設定檔裡的瀏覽器偏好設定。見瀏覽器偏好設定。
ready.json 在 devAdditions 下列出每一項及其原因。這些列裡的東西都不會隨擴充功能發布。執行 extension build 並閱讀 dist/<browser>/manifest.json,就能看到商店實際收到的內容。
第一個頁面會等待啟動時的註冊
background 腳本可以在啟動時用scripting.registerContentScripts 註冊 content script。在這個呼叫回應之前載入的頁面,永遠不會執行被註冊的腳本。
從 4.1.39 之後的版本起,dev 會按住第一個頁面,直到 background 完成它的啟動工作。這也包括在 await 過的呼叫(例如 fetch 或一次 storage 讀取)之後才做的註冊。等待的上限大約是五秒,所以頁面一定會開啟。
放在計時器後面的註冊不會被等待。dev 無法知道 setTimeout 回呼或 alarm 什麼時候觸發。
CLI 可能印出兩行。等待逾時時印出第一行:
start 和 preview 以同樣的方式按住第一個頁面,等待 background 啟動時或一次 storage 讀取之後做的註冊。它們不會等待放在 await 過的 fetch 或計時器後面的註冊。對於這些註冊,如果註冊在最初 15 秒內到達,它們會印出第二行。
自動化中介資料(建議用於腳本/代理)
當dev 執行時,Extension.js 會發出機器可讀的中介資料於:
dist/extension-js/<browser>/ready.jsondist/extension-js/<browser>/events.ndjson(以換行分隔的 JSON)
ready.json 視為就緒契約:
- 啟動中:
status: "starting" - 建置編譯完成:
status: "ready"。從 4.1.39 之後的版本起,帶--allow-control或--allow-eval並啟動了瀏覽器時,ready還會等待 background 連上,最多 10 秒。從 4.1.41 之後的版本開始,需要啟動瀏覽器時,編譯之後status仍保持starting,等啟動器蓋上browserPid、binary、profilePath與除錯器連接埠(Chromium 上是cdpPort,Firefox 上是rdpPort)之後才變為ready。executorAttachedAt可以出現在ready之後,除非工作階段是帶--allow-control或--allow-eval啟動的,這時ready會等它,最多 10 秒 - 啟動/編譯失敗:
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)公開瀏覽器的除錯埠號。從 4.1.41 之後的版本開始,同時啟動的工作階段各自取得自己的除錯埠號,所以請讀取這些欄位,不要假定是 9222profilePath、browserPid與extensionId由瀏覽器啟動器在啟動後寫入
events.ndjson 只屬於目前這次執行:新一次執行開始時檔案會重設,且每筆記錄都蓋上本次執行的 runId(與 ready.json 一致),消費端不會看到上一個工作階段的事件與目前的交錯。
工作階段行為異常時,執行 extension doctor——它依序檢查契約、控制通道、權杖、執行器與瀏覽器,並指出第一個失敗的環節與修復方式。
阻止瀏覽器啟動
兩個旗標聽起來很像,作用卻不同:--no-browser 是無頭、CI 與遠端工作的執行模式,也是 Playwright E2E 工作流程所依賴的旗標。它還有設定寫法 commands.dev.noBrowser: true,以及環境變數寫法 EXTENSION_CLI_NO_BROWSER=1。
--no-open 只是啟動時的一個細節。當你希望瀏覽器停在它原本顯示的頁面上,而不讓 Extension.js 在上面為你的擴充功能開啟分頁時,就用它。dev、start 與 preview 都接受這兩個旗標。
--no-browser 與就緒同步
--no-browser 只會關閉瀏覽器啟動,但完整的開發迴圈仍然保留。開發伺服器依然監看你的檔案,並在每次重建後透過控制橋向擴充功能的 service worker 廣播一次重新載入,因此即使沒有被啟動的瀏覽器在驅動,你的變更也會生效:
- content script 的變更會就地重新注入到已開啟的相符分頁(service worker 會用最新建置執行
chrome.scripting.executeScript),所以存檔後頁面就會更新,不需手動重新整理。之後才開啟的分頁也會拿到新的建置,因為 service worker 會動態重新註冊 content script(chrome.scripting.registerContentScripts)。 - service worker / manifest 的變更會重啟擴充功能。
--no-browser 的表現就像一般的 dev 工作階段:把建置好的 dist/<browser> 載入任何你能控制的瀏覽器,它就會在你存檔時持續更新。(如果你想要永不重新載入的靜態開發包,請用 --no-reload,見下文。)
--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 需要本地專案路徑。傳入遠端 URL 會以 E_ARGS 結束。
在同一次指令中同時傳入 --wait 與 --no-browser 會以 E_INVALID_OPTION 結束,因為 --wait 只讀取另一個程序寫出的契約。請像上面的步驟那樣把它們當成兩個程序執行。
從 4.1.21 開始,當 --wait 在產生者還在寫入 ready.json 時讀到它,會把這個寫到一半的檔案當作又一種暫態,繼續輪詢。到 4.1.20 為止,一次撕裂讀取會讓等待以 JSON 解析錯誤失敗。始終無法解析的檔案仍會以 E_READY_TIMEOUT 結束,逾時訊息會點明原因:The last read of the file failed to parse as JSON,後面接著解析器自己的錯誤。
用 --output json 取得機器輸出
--output json 會在 stdout 印出 schema-1 信封,每行一個 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 契約。 - 從 4.1.41 之後的版本開始,瀏覽器拒絕載入擴充功能時不會停止工作階段。串流裡會帶一個
ok: false訊框,其中status: "load-refused"、error.code: "E_EXTENSION_LOAD_REFUSED"。針對該工作階段的dev --wait會回答同樣的狀態與代碼,並以1結束。工作階段會在下一次儲存時重新嘗試載入。見 Manifest 拒絕。 - 從 4.1.41 之後的版本起,
dev還在尋找專案時的拒絕不會在 stderr 上印出任何內容。 - 之後的失敗,例如拋出例外的設定檔,也會在 stderr 上印出給人看的文字。
- 從 4.1.41 之後的版本起,無法建置的重新啟動會送出
restart-failed訊框。 - 先前的建置繼續提供服務。見重新啟動與關閉。
- 每個工作階段的最後一個訊框是
stopped或failed。
用 --no-reload 取得乾淨的開發包
--no-reload 會略過 content script 的重新注入包裝,以及重建時的 reload dispatch。開發版的 dist 會更接近正式版打包,並且當檔案變更時不會擾動已開啟的分頁。請自行重新載入擴充功能或頁面以套用變更。
--no-reload 只在 extension dev 支援。把它傳給 start、preview 或 build 會以錯誤結束。它在內部會設定 EXTENSION_NO_RELOAD=true,讓 develop 程序能從 CLI argv 之外讀取它。
dev 建置會輸出 cheap-module-source-map 類型的 source map,描述的是你的原始碼:原始的 TypeScript 與精確的行號,涵蓋 content script、傳統多檔案群組、background 以及兩個 manifest 版本下的頁面。不會使用任何 eval 變體,因此 bundle 在你自己的 CSP 下執行。
記錄旗標
這些旗標仍是實驗性的,可能在小版本之間變動。共用全域選項
也支援 全域旗標.Monorepo 與 workspace 根目錄
你可以將dev(以及 build)指向 monorepo 的根目錄,而不是擴充功能套件本身。Extension.js 會偵測 workspace 根目錄並自動解析其中的擴充功能套件:
pnpm workspace 成員從根目錄安裝
從 4.1.18 開始,當專案是 pnpm workspace 的成員且相依套件缺少時,自動安裝會從 workspace 根目錄執行,而不是從套件資料夾執行。安裝範圍過濾為該成員及其 workspace 相依套件:pnpm install 一致。安裝執行之前,工作階段會印出一行 info:
自動安裝相依套件
當dev 或 build 發現專案相依套件缺少時,會在編譯之前安裝它們。從 4.1.41 之後的版本起,只有專案自己的套件管理器會執行這次安裝。Extension.js 依以下順序選定它:
- 專案根目錄的鎖定檔:
pnpm-lock.yaml、yarn.lock、bun.lockb、bun.lock,然後是package-lock.json。 package.json中的packageManager欄位。EXTENSION_JS_PACKAGE_MANAGER,或EXTENSION_JS_PM_EXEC_PATH、npm_execpath中的套件管理器路徑。- Deno 專案:有
deno.lock,或有deno.json、deno.jsonc且旁邊沒有package.json。 - 執行指令的那個套件管理器,讀取自
npm_config_user_agent的第一個詞。 - npm。
PATH 上有哪些套件管理器,所以同一個專案在每台機器上都選定同一個套件管理器。選定的套件管理器失敗時,指令以 E_DEPENDENCY_INSTALL 停止。不會有別的套件管理器代替它,因為那會產生一棵鎖定檔沒有描述的相依樹。選定的套件管理器沒有安裝時,訊息會說明這一點,並告訴你如何安裝它。
新版本抵達 registry 期間的重試
一個新版本需要一兩分鐘才能抵達整個 npm registry。從 4.1.41 之後的版本起,當失敗是 registry 造成的時,安裝會再執行一次:- registry 列出了某個版本,但還沒有提供它的 tarball。
- 相依套件的相依套件要求一個 registry 還沒有列出的版本。
- registry 回應 5xx 或 429 狀態、重設連線、逾時,或 DNS 查詢失敗。
E_DEPENDENCY_INSTALL 停止:
從不重試的拒絕
有兩種失敗會立即以E_DEPENDENCY_INSTALL 停止安裝。Extension.js 從不重試它們,也從不繞過它們。
版本太新。 pnpm 的 minimumReleaseAge 與 Deno 的最小相依年齡會拒絕比限制更新的版本。訊息會說明是哪條規則,如果套件管理器印出了版本,也會給出該版本。要繼續,可以等到版本夠舊,或釘選到上一個版本。你也可以為這個套件放寬規則:pnpm 把它加入 minimumReleaseAgeExclude,Deno 在 deno.json 中設定 minimumDependencyAge。
Corepack 無法下載套件管理器。 套件管理器根本沒有啟動。訊息會給出 Corepack 請求的 registry,如果有 HTTP 狀態也會給出。如果 Extension.js 是因為 npm_config_registry 或專案的 .npmrc 指定了該 registry 才選用它,訊息也會說明。請檢查該 registry 是否提供這個套件管理器、你能否連上它,或把 COREPACK_NPM_REGISTRY 設為一個能提供它的 registry。
範例
執行本地擴充功能
從 GitHub 執行遠端擴充功能
將 GitHub 樹狀 URL 當作引數,即可在本機開發遠端擴充功能:在 Firefox 中執行
依序在多個瀏覽器中執行
在 Docker 或 dev container 中執行
當你在 Docker、dev container 或 GitHub Codespaces 中執行時,將開發伺服器綁定到0.0.0.0,主機才連得到:
--port 0 讓作業系統自動挑選可用埠號:
綁定主機與可連線主機
--host 是開發伺服器綁定的位址。瀏覽器(HMR 用戶端與重新載入橋接)需要的是一個它真的能連線的位址,兩者未必是同一個值:
--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,以及烘焙進擴充功能裡的重新載入橋接。
--host 本身已經是具體位址時(例如 --host 192.168.1.50),那個值本來就可連線,會被直接使用。只有在綁定主機與瀏覽器面對的主機不同時,才需要 --public-host。
開發伺服器會檢查每個請求的 Host 標頭,作為對 DNS 重新綁定的防禦。它回應 localhost、IP 位址、綁定主機與 --public-host。用其他任何名稱送來的請求都會得到 403,純文字內文寫明被拒絕的主機與修正方式,終端機上也會為每個被拒絕的主機印出一行。用 --allowed-hosts 放行更多名稱,它是逗號分隔的清單,前導的點允許所有子網域,也可以寫在 extension.config.js 的 commands.dev.allowedHosts 裡(陣列或逗號分隔的字串)。當開發伺服器是透過 docker 服務名稱、隧道主機名稱或 mDNS 名稱被連到、而瀏覽器撥號的目標不該改變時,就用它。
--host 0.0.0.0 不會放行所有名稱。綁定位址與放行的名稱是兩個獨立的設定。
將 Brave 作為自訂執行檔執行
最佳實務
- 瀏覽器相容性: 在不同瀏覽器中測試,確認每個目標都能正常運作。
- 使用 polyfill:
dev中 polyfill 預設關閉。Chromium 148 及更新版本原生提供browser,所以只有面向更舊的版本時才需要傳入--polyfill。在低於 152 的 Chromium 上,宣告了devtools_page的擴充功能在任何指令碼裡都沒有browser物件。請參閱跨瀏覽器相容性。 - 自動化可靠性: 把
dev視為監看模式的搭配(--no-browser+dev --wait)。把start視為正式版的搭配(--no-browser+start --wait)。對腳本與 CI 自動化,使用--output=json。
後續步驟
- 用
build產生正式版產物。 - 用
start驗證正式版啟動流程。 - 透過 瀏覽器專屬 manifest 欄位 了解瀏覽器目標。
- 在
extension.config.js中集中設定共用預設值。 - 在 環境變數 中了解設定的環境檔載入行為。

