preview 不会编译你的项目。它会加载一个已存在的未打包扩展根目录，并运行浏览器启动流程。
什么时候使用 preview
- 想运行已有的构建输出，而不重新构建。
- 快速对比已打包行为在多个浏览器目标上的表现。
- 调试与生产产物相关、而非与 dev / watch 模式相关的运行时问题。
preview 命令的能力
| 能力 | 你得到什么 |
|---|---|
| 构建输出验证 | 不重新构建即可测试真实的生产产物 |
| 浏览器目标检查 | 在所选浏览器目标上运行已编译的输出 |
| runner 控制 | 根据工作流需要启动或跳过浏览器 runner |
| 快速手动 QA | 发布前快速验证打包就绪的行为 |
preview是 run-only 的。它会优先使用已存在的dist/<browser>。你也可以让它指向其他已包含manifest.json的未打包扩展文件夹。
用法
preview 如何决定运行哪个目录
preview 按以下顺序检查：
- 所选浏览器目标对应的
dist/<browser>。 - 提供的项目路径或当前工作目录。
manifest.json 的未打包扩展。是否在同一条命令里跑过 build 并不重要。
参数与 flag
| flag | 别名 | 作用 | 默认值 |
|---|---|---|---|
[path] | - | 从项目路径预览已构建的扩展。 | process.cwd() |
--browser <browser> | - | 浏览器 / 引擎目标（chromium、chrome、edge、firefox 等）。 | chromium |
--profile <path|boolean> | - | 浏览器 profile 路径或布尔的 profile 模式。 | 全新 profile |
--chromium-binary <path> | - | 自定义的 Chromium 家族二进制路径。 | 系统默认 |
--gecko-binary <path> | --firefox-binary | 自定义的 Gecko 家族二进制路径。 | 系统默认 |
--starting-url <url> | - | 启动浏览器时的起始 URL。 | 未设置 |
--no-browser | - | 跳过浏览器启动。 | 默认启用浏览器启动 |
--port <port> | - | 启用 runner 时使用的 runner / devtools 端口。用 0 让 OS 自动分配端口。 | 8080 |
--host <host> | - | 绑定 dev 服务器的主机。Docker / dev container 中可用 0.0.0.0。 | 127.0.0.1 |
--extensions <list> | - | 用逗号分隔的协同扩展或商店 URL。 | 未设置 |
--author | --author-mode | 启用维护者诊断信息。 | 关闭 |
自动化元数据
preview 会把就绪元数据写入：
dist/extension-js/<browser>/ready.json
--no-browser 流程，它提供了确定性的命令状态：
- 命令初始化时为
starting - run-only 验证完成时为
ready - 缺少所需输出或启动失败时为
error runId与startedAt用于在脚本 / agent 中做会话关联
preview 不提供 --wait 闸门 flag。preview 的自动化请直接消费 ready.json。
日志 flag
| flag | 作用 | 默认值 |
|---|---|---|
--logs <off|error|warn|info|debug|trace|all> | 最低日志级别。 | off |
--log-context <list|all> | 上下文过滤（background、content、page、sidebar、popup、options、devtools）。 | all |
--log-format <pretty|json|ndjson> | 日志器输出格式。 | pretty |
--no-log-timestamps | 在 pretty 模式下关闭时间戳。 | 默认启用时间戳 |
--no-log-color | 在 pretty 模式下关闭颜色。 | 默认启用颜色 |
--log-url <pattern> | 按 URL 子串 / 正则过滤日志事件。 | 未设置 |
--log-tab <id> | 按 tab ID 过滤日志事件。 | 未设置 |
源代码检视 flag（preview 不支持）
CLI 会在解析前检测到这些 flag 并以错误退出。请改用 dev --source ...。
| flag | 在 preview 中的支持情况 |
|---|---|
--source [url] | 不支持（命令会带指引退出） |
--watch-source [boolean] | 不支持（命令会带指引退出） |
--source-format <pretty|json|ndjson> | 不支持（命令会带指引退出） |
--source-summary [boolean] | 不支持（命令会带指引退出） |
--source-meta [boolean] | 不支持（命令会带指引退出） |
--source-probe <selectors> | 不支持（命令会带指引退出） |
--source-tree <off|root-only> | 不支持（命令会带指引退出） |
--source-console [boolean] | 不支持（命令会带指引退出） |
--source-dom [boolean] | 不支持（命令会带指引退出） |
--source-max-bytes <bytes> | 不支持（命令会带指引退出） |
--source-redact <off|safe|strict> | 不支持（命令会带指引退出） |
--source-include-shadow <off|open-only|all> | 不支持（命令会带指引退出） |
--source-diff [boolean] | 不支持（命令会带指引退出） |
共享的全局选项
也支持 全局 flag。示例
预览一个本地扩展
在 Edge 与 Chrome 中预览
不启动浏览器进行预览
行为说明
preview是 run-only 的，永远不会编译项目。preview优先使用已有的构建输出（dist/<browser>），但也可以回落到另一个未打包扩展根目录。preview不会运行 watch 模式，也不提供热模块替换（HMR）。preview不支持源代码检视 flag；那种工作流请用dev。- 对于脚本 / agent，请依赖
ready.json，避免解析终端输出。
最佳实践
- 测试新鲜的生产产物时，先跑
build再跑preview。 - 当你的未打包扩展位于默认项目输出之外时，请传入项目路径参数。
- 打包前用
--browser在多个目标上验证行为。
下一步
- 一步构建并启动：用
start。 - 生成生产产物：用
build。 - 在
extension.config.js中集中配置共享默认值。 - 在 环境变量 中查看配置期 env 加载行为。