preview 不會編譯你的專案,它會載入既有的未打包擴充功能根目錄,並執行瀏覽器啟動流程。
何時使用 preview
- 不重新建置,直接執行既有的建置輸出。
- 快速比較不同瀏覽器目標下的打包後行為。
- 除錯與正式版產物有關、而非開發/監看模式的執行階段問題。
Preview 指令功能
preview只執行,不建置。當dist/<browser>輸出存在時優先使用。你也可以指向其他已包含manifest.json的未打包擴充功能資料夾。
用法
preview 如何選擇要執行的內容
preview 會依序檢查這些位置:
- 你傳入的
--output-path <dir>。它的優先權高於其他一切。 - 所選瀏覽器目標的
dist/<browser>。 - 你提供的專案路徑或目前工作資料夾。
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:讓腳本/代理可關聯特定工作階段
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在打包前跨目標驗證行為。
後續步驟
- 用
start在一個步驟完成建置與啟動。 - 用
build產生正式版產物。 - 在
extension.config.js中集中設定共用預設值。 - 在 環境變數 中了解設定的環境檔載入行為。

