preview 不会编译你的项目。它会加载一个已存在的未打包扩展根目录，并运行浏览器启动流程。
什么时候使用 preview
- 想运行已有的构建输出，而不重新构建。
- 快速对比已打包行为在多个浏览器目标上的表现。
- 调试与生产产物相关、而非与 dev / watch 模式相关的运行时问题。
preview 命令的能力
preview是 run-only 的。它会优先使用已存在的dist/<browser>。你也可以让它指向其他已包含manifest.json的未打包扩展文件夹。
用法
preview 如何决定运行哪个目录
preview 按以下顺序检查：
- 你传入的
--output-path <dir>。它的优先级高于其他一切。 - 所选浏览器目标对应的
dist/<browser>。 - 提供的项目路径或当前工作目录。
manifest.json 的未打包扩展。是否在同一条命令里跑过 build 并不重要。
参数与 flag
--author 与 --author-mode 是 --debug 的隐藏、已废弃别名。
浏览器支持
preview 没有 Safari 路径。传入 --browser safari（或 webkit-based）会以 E_COMMAND_UNSUPPORTED_FOR_TARGET 退出。Safari 是受支持的浏览器，但这个命令无法启动它。Safari 目标请使用 dev 或 build。
远程 URL 与 light 模式
当路径参数是一个远程http(s) URL 时，preview 会自动设置 EXTJS_LIGHT=1。这会让下载下来的扩展以 light 模式启动。如果你事先自己设置了 EXTJS_LIGHT，则会覆盖这一行为。
自动化元数据
preview 会把就绪元数据写入：
dist/extension-js/<browser>/ready.json
--no-browser 流程，它提供了确定性的命令状态：
- 命令初始化时为
starting - run-only 验证完成时为
ready - 缺少所需输出或启动失败时为
error runId与startedAt用于在脚本 / agent 中做会话关联
preview 不提供 --wait 闸门 flag。preview 的自动化请直接消费 ready.json。
用 --output json 输出机器可读结果
--output json 会在 stdout 打印一个 schema-1 信封：
- 运行成功时打印一个
status: "ready"帧。它的value携带项目路径以及被预览的浏览器列表。 - 当没有可预览的内容时，该帧为
ok: false，并带有status: "not-found"与error.code: "E_PREVIEW_NO_DIST"。它的提示会让你先运行extension build。 - 其他失败会打印
ok: false与status: "failed"，随后进程以1退出。
日志 flag
这些 flag 是实验性的，可能在小版本之间发生变化。共享的全局选项
也支持 全局 flag。示例
预览一个本地扩展
在 Edge 与 Chrome 中预览
不启动浏览器进行预览
行为说明
preview是 run-only 的，永远不会编译项目。preview优先使用已有的构建输出（dist/<browser>），但也可以回落到另一个未打包扩展根目录。preview不会运行 watch 模式，也不提供热模块替换（HMR）。- 对于脚本 / agent，请依赖
ready.json，避免解析终端输出。
最佳实践
- 测试新鲜的生产产物时，先跑
build再跑preview。 - 当你的未打包扩展位于默认项目输出之外时，请传入项目路径参数。
- 打包前用
--browser在多个目标上验证行为。
下一步
- 一步构建并启动：用
start。 - 生成生产产物：用
build。 - 在
extension.config.js中集中配置共享默认值。 - 在 环境变量 中查看配置期 env 加载行为。