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

何時使用 start

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

Start 指令功能

與其他指令的差異

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

用法

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

引數與旗標

在 Firefox 上,--starting-url 會在附加元件安裝完成後才開啟,所以你的 document_start content script 會在該頁面上執行。從 4.1.39 之後的版本起,它不再取代你的擴充功能自己開啟的分頁。 有兩個已淘汰的別名雖然從 --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 同樣會拒絕 chromium-emulator,並以 E_UNSUPPORTED_BROWSER 結束。模擬的 Chromium 頁面要從開發伺服器讀取你的建置,而 start 不會執行開發伺服器。這個目標請改用 dev。

自動化中介資料

start 會把就緒中介資料寫入:
  • dist/extension-js/<browser>/ready.json
當使用 --no-browser 時,這對自動化非常有用:
  • 等待 status: "ready" 後再啟動外部 runner。
  • 將 status: "error" 視為確定性的失敗訊號。
  • 使用 runId 與 startedAt 關聯特定的執行階段。
從 4.1.41 之後的版本開始,同時啟動的工作階段各自取得自己的除錯埠號。請從 ready.json 裡讀取 cdpPort 或 rdpPort,不要假定是 9222。卡片印出時,cdpPort 已經在記錄裡。 從 4.1.39 之後的版本起,帶 --allow-control 或 --allow-eval 時,狀態會保持 starting,直到擴充功能的 background 連上,或者過去 10 秒。要知道 act 指令能否執行,請讀取 executorAttachedAt。見 ready.json 契約。 從 4.1.39 之後的版本起,這類工作階段給出的拒絕訊息會把 extension start 寫成需要重新啟動的指令。沒有 background 腳本或 service worker 的建置無法被控制:工作階段在啟動時會給出警告,每一個 act 指令都會回答這個建置沒有 background。見 start 或 preview session 上的拒絕。 工作階段結束之後,act 指令會如實說明,並印出重新啟動它的 extension start 指令。見 session 已經結束時。

阻止瀏覽器啟動

兩個旗標聽起來很像,作用卻不同:
--no-browser 還有設定寫法 commands.start.noBrowser: true,以及環境變數寫法 EXTENSION_CLI_NO_BROWSER=1。dev、start 與 preview 都接受這兩個旗標。 從 4.2.0 之後的版本起,start --no-browser 的卡片會在 Browser 列標上 (no-browser mode),與 dev 和 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 影格。
  • 從 4.2.0 之後的版本起,SIGINT 或 SIGTERM 會以一個帶 E_INTERRUPTED、value.signal 與 value.browsers 的 stopped 影格結束串流,執行以 0 結束。建置仍在進行時到達的訊號會以同樣的影格結束它,執行以 130 或 143 結束。請見 生命週期串流。
  • 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。
  • 從 4.1.41 之後的版本開始,瀏覽器拒絕載入擴充功能時會印出一個 ok: false 影格,其中 status: "load-refused"、error.code: "E_EXTENSION_LOAD_REFUSED"。start 會停止瀏覽器並以 1 結束。針對這次執行的 start --wait 會回答同樣的狀態與代碼。見 Manifest 拒絕。

記錄旗標

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

共用全域選項

也支援 全域旗標。

範例

以預設瀏覽器啟動

以 Firefox 啟動

建置但不啟動瀏覽器

行為說明

  • start 不會執行開發伺服器,也不提供 Hot Module Replacement (HMR) 或監看模式。
  • start 以正式版為導向;迭代式的本機開發請使用 dev。
  • 對機器消費者,請解析 dist/extension-js/<browser>/ready.json,而不是終端機文字。
  • 從 4.1.41 之後的版本開始,如果瀏覽器拒絕這個擴充功能,start 會停止瀏覽器並以結束代碼 1 結束。見 Manifest 拒絕。

後續步驟

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