用於啟動已建置擴充功能的 Preview 指令

​

何時使用 preview

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

​

Preview 指令功能

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

​

用法

extension preview [project-path] [options]

extension preview [project-path] [options]

extension preview [project-path] [options]

extension preview [project-path] [options]

extension preview [project-path] [options]

​

preview 如何選擇要執行的內容

1. 你傳入的 --output-path <dir>。它的優先權高於其他一切。
2. 所選瀏覽器目標的 dist/<browser>。
3. 你提供的專案路徑或目前工作資料夾。

​

引數與旗標

​

瀏覽器支援

​

遠端 URL 與 light 模式

​

阻止瀏覽器啟動

# 阻止瀏覽器啟動。
extension preview --no-browser

# 啟動瀏覽器,但不為擴充功能開啟分頁。
extension preview --no-open

​

自動化中介資料

• dist/extension-js/<browser>/ready.json

• starting:指令初始化中
• ready:僅執行的驗證完成
• error:缺少必要輸出或啟動失敗
• runId 與 startedAt:讓腳本/代理可關聯特定工作階段

​

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

• 執行成功會印出 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。
• 其他失敗會印出 ok: false 與 status: "failed",接著行程以 1 結束。

​

記錄旗標

​

共用全域選項

​

範例

​

預覽本地擴充功能

extension preview ./my-extension

extension preview ./my-extension

extension preview ./my-extension

extension preview ./my-extension

extension preview ./my-extension

​

在 Edge 與 Chrome 中預覽

extension preview ./my-extension --browser=edge,chrome

extension preview ./my-extension --browser=edge,chrome

extension preview ./my-extension --browser=edge,chrome

extension preview ./my-extension --browser=edge,chrome

extension preview ./my-extension --browser=edge,chrome

​

預覽但不啟動瀏覽器

extension preview ./my-extension --no-browser

extension preview ./my-extension --no-browser

extension preview ./my-extension --no-browser

extension preview ./my-extension --no-browser

extension preview ./my-extension --no-browser

​

行為說明

• preview 只執行,從不編譯專案。
• preview 優先使用既有的建置輸出(dist/<browser>),但可退回到其他未打包擴充功能根目錄。
• preview 不會執行監看模式或 Hot Module Replacement (HMR)。
• 腳本/代理請依賴 ready.json,避免解析終端機輸出。

​

最佳實務

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

​

後續步驟

• 用 start 在一個步驟完成建置與啟動。
• 用 build 產生正式版產物。
• 在 extension.config.js 中集中設定共用預設值。
• 在 環境變數 中了解設定的環境檔載入行為。