Skip to main content
每個指令解析一份 JSON 文件,而不是去刮取記錄行。 在 --output json 之下,每個會結束的指令都會在 stdout 上剛好回一個 schema-1 信封。長時間執行的指令則以 生命週期影格 的形式串流出同樣的結構。

信封結構

error 物件:

成功與失敗範例

編譯診斷

失敗的 build 影格和 dev 串流的 compile-failed 影格會帶著 error.details,每條編譯器診斷一個條目,錯誤排在前面。每個條目的結構如下: 清單上限為 20 條。當上限把它截斷時,該影格會設定 truncated: true。 可能出現在 details 裡的錯誤碼是錯誤碼表中的診斷列:E_MODULE_NOT_FOUND、E_CONTENT_SCRIPT_SYNTAX、E_CSS_PARSE、E_ENTRY_NOT_FOUND、E_ASSET_MISSING、E_SCRIPT_DEP_MISSING、E_RESERVED_FOLDER、E_CSS_PREPROCESSOR_MISSING、E_CSS_DEAD_REF、E_LOCALES_LAYOUT、E_WAR_INVALID、E_BACKGROUND_REQUIRED、E_REMOTE_RESOURCE_BLOCKED、E_PERF_BUDGET 和 E_ENV_NO_MATCH。 下面是 golden.build.compile.json,其中兩條 message 縮短為各自的第一行:
成功的建置會把警告保留在頂層的 warnings 陣列裡。當能解析出錯誤碼時,那裡的每個字串都以 E_CODE: 開頭,例如 E_CSS_DEAD_REF: ...,與 logs 和 uninstall 既有的慣例相同。

給人看的文案去哪了

EXTENSION_OUTPUT 環境變數是機器模式的開關。當它是 json 或 ndjson 時,影格獨佔 stdout,給人看的文案讓路:
  • 資訊性輸出與警告會安靜下來,或在串流需要時改走 stderr。
  • 錯誤文案永遠不會被抑制。它一律寫到 stderr,所以啟動失敗仍然看得見,而 stdout 保持可解析。
把 stdout 接給你的解析器,把 stderr 留給人。兩者永不混在一起。

公開的契約產物

extension-develop 套件透過 ./contract/* export,把契約當成可匯入的檔案一併發佈: 請用這份 schema 驗證你的消費端,並把測試釘在 golden 固件上。錯誤碼只會新增,永遠不會被改名或移除。

後續步驟