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/* 导出,把契约作为可导入的文件一起发布: 请用这份 schema 校验你的消费方,并把测试固定到 golden 固件上。错误码只会新增,永远不会被改名或删除。

下一步