Skip to main content
當你想用一個指令完成正式版建置並立刻啟動瀏覽器時,使用 start。 start 指令會先執行正式版建置,然後用與 preview 相同的流程啟動已建置的擴充功能。

​
何時使用 start

  • 編譯後立即手動驗證正式版行為。
  • 重現監看模式與正式版輸出之間的執行階段差異。
  • 在本機進行接近正式版的檢查,而不必分開執行 build 再 preview。

​
Start 指令功能

​
與其他指令的差異

  • dev:開發伺服器 + Hot Module Replacement (HMR)/監看模式
  • build:只做正式版建置
  • preview:在不建置的情況下啟動既有的擴充功能
  • start:依序執行 build + preview

​
用法

如果省略路徑,指令會使用目前工作資料夾。

​
引數與旗標

有兩個已淘汰的別名雖然從 --help 隱藏,但仍可使用:
  • --wait-format <pretty|json> 會對應到 --output,並在 stderr 警告一次。請把腳本改用 --output。
  • --author 與 --author-mode 會對應到 --debug。

​
瀏覽器支援

start 沒有 Safari 路徑。傳入 --browser safari(或 webkit-based)會以 E_COMMAND_UNSUPPORTED_FOR_TARGET 結束。這個結論是量測出來的:Safari 的 WebDriver 路徑確實能載入未封裝的資料夾,background 也確實會執行,但 Safari 給這個擴充功能的主機來源是零個。content script 永遠不會注入,之後也沒有任何 API 呼叫可以補上這個存取權。Safari 目標請改用 dev 或 build。

​
自動化中介資料

start 會把就緒中介資料寫入:
  • dist/extension-js/<browser>/ready.json
當使用 --no-browser 時,這對自動化非常有用:
  • 等待 status: "ready" 後再啟動外部 runner。
  • 將 status: "error" 視為確定性的失敗訊號。
  • 使用 runId 與 startedAt 關聯特定的執行階段。

​
阻止瀏覽器啟動

兩個旗標聽起來很像,作用卻不同:
--no-browser 還有設定寫法 commands.start.noBrowser: true,以及環境變數寫法 EXTENSION_CLI_NO_BROWSER=1。dev、start 與 preview 都接受這兩個旗標。

​
--no-browser 與就緒同步

--no-browser 只會關閉瀏覽器啟動。在正式版建置完成前,它不會阻擋外部 runner。 對以正式版為主的 Playwright、持續整合(CI)與 AI 工作流程:
  1. 以產生者程序執行 extension start --no-browser。
  2. 用 extension start --wait --browser=<browser> 作為就緒閘道。
  3. 只在 status: "ready" 後才啟動外部瀏覽器自動化。
--wait 在 error/逾時時以非零碼結束,並會忽略來自已死程序(pid 不存在)的過期契約。 因為 start 可能很快就結束,只要時間戳落在 60 秒的視窗內,已完成執行留下的契約一樣算數。 --wait 需要本地專案路徑。傳入遠端 URL 會以 E_ARGS 結束。 在同一次指令中同時傳入 --wait 與 --no-browser 會以 E_INVALID_OPTION 結束,因為 --wait 只讀取另一個程序寫出的契約。請像上面的步驟那樣把它們當成兩個程序執行。

​
用 --output json 取得機器可讀輸出

--output json 會在 stdout 印出 schema-1 信封,每行一個 JSON 物件:
  • 一般的 start 執行會在建置完成、瀏覽器啟動之後印出一個 status: "started" 影格。它帶有專案路徑、瀏覽器清單、pid 與 port: null,因為只執行不建置的工作階段不會綁定任何埠號。失敗的執行只會印出它的失敗影格,前面永遠不會有 started 影格。
  • start --wait 執行成功時會印出一個 status: "ready" 影格。它的 value.results 陣列會按瀏覽器帶出完整的就緒契約。
  • start --wait 讀到處於 error 狀態的契約時,會印出一個指明原因的 ok: false 影格,例如瀏覽器根本沒有啟動時的 E_BROWSER_LAUNCH,或瀏覽器結束時的 E_BROWSER_EXITED。完整清單見 ready.json 契約。
  • 建置失敗時會印出一個 ok: false 影格,其中 status: "build-failed",接著程序以 1 結束。編譯錯誤帶 error.code: "E_COMPILE"。專案資料夾不存在帶 E_PROJECT_NOT_FOUND,資料夾裡沒有 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 固定的執行檔有問題時會印出一個 ok: false 影格,其中 status: "usage",error.code: "E_BROWSER_BINARY_INVALID"。這包括路徑不存在、檔案無法執行,以及執行檔在 10 秒內沒有回應版本探測。命令隨即結束,不會留下任何執行中的程序。
  • 瀏覽器無法啟動時會印出一個 ok: false 影格,其中 status: "failed"。二進位檔可以執行但系統無法啟動它,或 Firefox 在除錯器回應之前就結束時為 E_BROWSER_LAUNCH,Firefox 在執行但除錯器始終沒有回應時為 E_BROWSER_CONNECT。

​
記錄旗標

這些旗標屬於實驗性質,可能在次版本之間變動。

​
共用全域選項

也支援 全域旗標。

​
範例

​
以預設瀏覽器啟動

​
以 Firefox 啟動

​
建置但不啟動瀏覽器

​
行為說明

  • start 不會執行開發伺服器,也不提供 Hot Module Replacement (HMR) 或監看模式。
  • start 以正式版為導向;迭代式的本機開發請使用 dev。
  • 對機器消費者,請解析 dist/extension-js/<browser>/ready.json,而不是終端機文字。

​
後續步驟

  • 用 dev 進行快速迭代。
  • 用 preview 啟動既有的建置輸出。