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 目標請改用 dev 或 build。

​
自動化中介資料

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

​
--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,--wait 優先,指令會以「僅等待」模式執行。

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

--output json 會在 stdout 印出 schema-1 信封,每行一個 JSON 物件:
  • 一般的 start 執行會在建置前印出一個 status: "started" 影格。它帶有專案路徑、瀏覽器清單、要求的埠號與 pid。
  • start --wait 執行成功時會印出一個 status: "ready" 影格。它的 value.results 陣列會按瀏覽器帶出完整的就緒契約。
  • 建置失敗時會印出一個 ok: false 影格,其中 status: "build-failed"、error.code: "E_COMPILE",接著程序以 1 結束。

​
記錄旗標

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

​
共用全域選項

也支援 全域旗標。

​
範例

​
以預設瀏覽器啟動

​
以 Firefox 啟動

​
建置但不啟動瀏覽器

​
行為說明

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

​
後續步驟

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