跳轉到主要內容
啟動已建置的擴充功能輸出進行接近正式版的手動測試。 preview 不會編譯你的專案,它會載入既有的未打包擴充功能根目錄,並執行瀏覽器啟動流程。

何時使用 preview

  • 不重新建置,直接執行既有的建置輸出。
  • 快速比較不同瀏覽器目標下的打包後行為。
  • 除錯與正式版產物有關、而非開發/監看模式的執行階段問題。

Preview 指令功能

preview 只執行,不建置。當 dist/<browser> 輸出存在時優先使用。你也可以指向其他已包含 manifest.json 的未打包擴充功能資料夾。

用法

如果省略路徑,Extension.js 會使用目前工作資料夾。

preview 如何選擇要執行的內容

preview 會依序檢查這些位置:
  1. 你傳入的 --output-path <dir>。它的優先權高於其他一切。
  2. 所選瀏覽器目標的 dist/<browser>。
  3. 你提供的專案路徑或目前工作資料夾。
該資料夾必須包含含有 manifest.json 的未打包擴充功能。是否在同一個指令中執行過 build 並不重要。

引數與旗標

在 Firefox 上,--starting-url 會在附加元件安裝完成後才開啟,所以你的 document_start content script 會在該頁面上執行。從 4.1.39 之後的版本起,它不再取代你的擴充功能自己開啟的分頁。 --author 與 --author-mode 是 --debug 的隱藏、已淘汰別名。

瀏覽器支援

preview 沒有 Safari 路徑。傳入 --browser safari(或 webkit-based)會以 E_COMMAND_UNSUPPORTED_FOR_TARGET 結束。Safari 是受支援的瀏覽器,但這個指令無法啟動它。這個結論是量測出來的:Safari 的 WebDriver 路徑確實能載入未封裝的資料夾,background 也確實會執行,但 Safari 給這個擴充功能的主機來源是零個。content script 永遠不會注入,之後也沒有任何 API 呼叫可以補上這個存取權。Safari 目標請改用 dev 或 build。 preview 同樣會拒絕 chromium-emulator,並以 E_UNSUPPORTED_BROWSER 結束。模擬的 Chromium 頁面要從開發伺服器讀取你的建置,而 preview 不會執行開發伺服器。這個目標請改用 dev。

遠端 URL 與 light 模式

當路徑引數是遠端 http(s) URL 時,preview 會自動設定 EXTJS_LIGHT=1。這會讓下載回來的擴充功能以 light 模式啟動。若你事先自行設定 EXTJS_LIGHT,就會覆寫這個行為。 在 --output json 下,下載進度行會寫到 stderr,因此 stdout 只包含結果影格。

遠端壓縮檔會放在哪裡

遠端壓縮檔會解壓到你的快取裡,而不是你執行指令的資料夾。資料夾以 URL 路徑命名,並加上一段短摘要,所以同一個壓縮檔永遠落在同一個地方: 同一個 URL 第二次執行時會直接重用這份副本而不再下載,並會說明這點。刪除該資料夾即可重新下載。URL 的查詢字串(分享 token 所在之處)不屬於 key 的一部分,也永遠不會寫到磁碟。 傳入 --output-path <dir> 可以改為解壓到你指定的資料夾。如果該資料夾已經存在,而且不是從這個 URL 解壓出來的,指令會以 E_DESTINATION_NOT_EMPTY 拒絕,並保持原樣不動。 從終端機複製的連結若曾被折行,token 裡可能夾帶空格。preview 會移除這些空格,並在下載前說明。伺服器回應 401 或 403 時,會以 E_REMOTE_ACCESS_DENIED 回報為連結被拒絕,若 token 帶有到期時間也會一併列出。

阻止瀏覽器啟動

兩個旗標聽起來很像,作用卻不同:
--no-browser 還有設定寫法 commands.preview.noBrowser: true,以及環境變數寫法 EXTENSION_CLI_NO_BROWSER=1。dev、start 與 preview 都接受這兩個旗標。 從 4.1.41 之後的版本起,當你傳入 --browser 時,preview 與 start 中的 extension.config.js 會看到 production env 檔,以及被預覽瀏覽器的檔案,例如 .env.firefox。見環境變數。

自動化中介資料

preview 會把就緒中介資料寫入:
  • dist/extension-js/<browser>/ready.json
沒有專案包住的資料夾(例如複製出來的建置資料夾)會把這些中繼資料保存在自身內部,位於 <folder>/dist/extension-js/。Extension.js 會加入一個說明該資料夾內容的 README.md,以及一個讓它不進入提交的 .gitignore。 對於 --no-browser 流程,它能提供確定性的指令狀態:
  • starting:指令初始化中
  • ready:僅執行的驗證完成
  • 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 preview 寫成需要重新啟動的指令。沒有 background 腳本或 service worker 的建置無法被控制:工作階段在啟動時會給出警告,每一個 act 指令都會回答這個建置沒有 background。見 start 或 preview session 上的拒絕。 工作階段結束之後,act 指令會如實說明,並印出重新啟動它的 extension preview 指令。見 session 已經結束時。 preview 沒有 --wait 閘道旗標。要把 preview 自動化,直接讀取 ready.json。

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

--output json 會在 stdout 印出一個 schema-1 信封:
  • 執行成功會印出 status: "ready" 影格。它的 value 帶有專案路徑與被預覽的瀏覽器清單。
  • 專案路徑不存在時,會印出 ok: false,並帶 status: "usage" 與 error.code: "E_PROJECT_NOT_FOUND"。資料夾存在但沒有 manifest 時,狀態相同,代碼為 E_MANIFEST_NOT_FOUND。這兩種影格都不帶提示。
  • 專案存在、但輸出路徑下沒有未封裝的擴充功能時,該影格為 ok: false,並帶 status: "not-found" 與 error.code: "E_PREVIEW_NO_DIST"。它的提示會請你先執行 extension build。
  • --chromium-binary 或 --gecko-binary 固定的執行檔有問題時,會印出 ok: false,並帶 status: "usage" 與 error.code: "E_BROWSER_BINARY_INVALID"。這包括路徑不存在、檔案無法執行,以及執行檔在 10 秒內沒有回應版本探測。命令隨即結束,不會留下任何執行中的程序。
  • 遠端 URL 沒有提供可用的封存檔時,會印出 ok: false 與 status: "failed"。回傳的不是 ZIP 封存檔、封存檔已損毀或含有位於其資料夾之外的條目時代碼為 E_REMOTE_ZIP_INVALID,逾時為 E_REMOTE_FETCH_TIMEOUT,連線遭拒或 HTTP 錯誤為 E_REMOTE_DOWNLOAD。
  • 瀏覽器無法啟動時會印出 ok: false 與 status: "failed"。二進位檔可以執行但系統無法啟動它,或 Firefox 在除錯器回應之前就結束時代碼為 E_BROWSER_LAUNCH,Firefox 在執行但除錯器始終沒有回應時為 E_BROWSER_CONNECT。設定檔載入失敗時會以同樣的狀態印出 E_CONFIG_LOAD。
  • 從 4.1.41 之後的版本開始,瀏覽器拒絕載入擴充功能時會印出 ok: false,其中 status: "load-refused"、error.code: "E_EXTENSION_LOAD_REFUSED"。preview 會停止瀏覽器並以 1 結束。見 Manifest 拒絕。
  • 其他失敗會印出 ok: false 與 status: "failed",接著行程以 1 結束。

記錄旗標

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

共用全域選項

也支援 全域旗標。

範例

預覽本地擴充功能

在 Edge 與 Chrome 中預覽

預覽但不啟動瀏覽器

行為說明

  • preview 只執行,從不編譯專案。
  • preview 優先使用既有的建置輸出(dist/<browser>),但可退回到其他未打包擴充功能根目錄。
  • preview 不會執行監看模式或 Hot Module Replacement (HMR)。
  • 從 4.1.41 之後的版本開始,如果瀏覽器拒絕這個擴充功能,preview 會停止瀏覽器並以結束代碼 1 結束。見 Manifest 拒絕。
  • 腳本/代理請依賴 ready.json,避免解析終端機輸出。

最佳實務

  • 測試全新的正式版產物時,先執行 build 再 preview。
  • 當你的未打包擴充功能不在預設的專案輸出位置時,請傳入專案路徑引數。
  • 使用 --browser 在打包前跨目標驗證行為。

後續步驟