start。
start 命令先跑生产构建，再用与 preview 相同的流程启动构建好的扩展。
什么时候使用 start
- 编译完成后立刻手动验证生产行为。
- 复现 watch 模式与生产输出之间的运行时差异。
- 在本地跑一次类生产检查，而不需要分别跑
build再跑preview。
start 命令的能力
| 能力 | 你得到什么 |
|---|---|
| 构建 + 启动工作流 | 一步完成生产编译与浏览器启动 |
| 目标选择 | 直接在所选浏览器或引擎目标上启动 |
| runner 控制 | 只需要构建验证时可以跳过浏览器启动 |
| 类生产验证 | 检查真实的编译输出，而不是 watch 模式状态 |
与其他命令的区别
dev：dev 服务器 + 热模块替换（HMR）/ watch 模式build：仅生产构建preview：不构建、直接启动已构建好的扩展start：依次执行build+preview
用法
参数与 flag
| flag | 别名 | 作用 | 默认值 |
|---|---|---|---|
[path or url] | - | 扩展路径或远程 URL。 | process.cwd() |
--browser <browser> | - | 浏览器 / 引擎目标。 | chromium |
--profile <path|boolean> | - | 浏览器 profile 路径或布尔的 profile 模式。 | 全新 profile |
--chromium-binary <path> | - | 自定义的 Chromium 家族二进制路径。 | 系统默认 |
--gecko-binary <path> | --firefox-binary | 自定义的 Gecko 家族二进制路径。 | 系统默认 |
--polyfill [boolean] | - | 为 Chromium 目标启用 browser.* API 兼容 polyfill。 | true |
--starting-url <url> | - | 启动浏览器时的起始 URL。 | 未设置 |
--no-browser | - | 构建但跳过浏览器启动。 | 默认启用浏览器启动 |
--wait [boolean] | - | 等待 dist/extension-js/<browser>/ready.json 并退出。 | 关闭 |
--wait-timeout <ms> | - | --wait 模式的超时时间。 | 60000 |
--wait-format <pretty|json> | - | 等待结果的输出格式（json 适合机器读取）。 | pretty |
--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。 | 未设置 |
--install [boolean] | - | 缺失依赖时安装项目依赖。 | 按命令默认行为 |
--author | --author-mode | 启用维护者诊断信息。 | 关闭 |
自动化元数据
start 会把就绪元数据写入：
dist/extension-js/<browser>/ready.json
--no-browser 时，这对自动化很有用：
- 在启动外部 runner 之前等待
status: "ready"。 - 把
status: "error"当作确定性的失败信号处理。 - 用
runId与startedAt关联某次具体的运行时会话。
--no-browser 与就绪同步
--no-browser 只会禁用浏览器启动。它并不会在生产构建完成之前阻塞外部 runner。
对于面向生产的 Playwright、持续集成（CI）和 AI 工作流：
- 把
extension start --no-browser作为生产者进程。 - 把
extension start --wait --browser=<browser>作为就绪闸门。 - 只有在
status: "ready"之后才启动外部浏览器自动化。
--wait 在 error / 超时时以非零状态退出，并会忽略来自已死进程（pid 已不存在）的过期契约。
如果你在同一次调用中同时传入 --wait 与 --no-browser，--wait 优先。命令会以 wait-only 模式运行。
日志 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（start 不支持）
CLI 会在解析前检测到这些 flag 并以错误退出。请改用 dev --source ...。
| flag | 在 start 中的支持情况 |
|---|---|
--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。示例
用默认浏览器启动
在 Firefox 中启动
构建但跳过浏览器启动
行为说明
start不会运行 dev 服务器，也不提供热模块替换（HMR）或 watch 模式。start面向生产模式；本地迭代开发请用dev。start不支持源代码检视选项。那种工作流请用dev --source ...。- 对于机器消费者，请解析
dist/extension-js/<browser>/ready.json，而不是终端文本。