Skip to main content
当你想用一条命令完成生产构建并立刻启动浏览器时，使用 start。 start 命令先跑生产构建，再用与 preview 相同的流程启动构建好的扩展。

​
什么时候使用 start

  • 编译完成后立刻手动验证生产行为。
  • 复现 watch 模式与生产输出之间的运行时差异。
  • 在本地跑一次类生产检查，而不需要分别跑 build 再跑 preview。

​
start 命令的能力

​
与其他命令的区别

  • dev：dev 服务器 + 热模块替换（HMR）/ watch 模式
  • build：仅生产构建
  • preview：不构建、直接启动已构建好的扩展
  • start：依次执行 build + preview

​
用法

如果省略路径，命令会使用当前工作目录。

​
参数与 flag

有两个已废弃的别名从 --help 中隐藏，但仍然可用：
  • --wait-format <pretty|json> 会映射到 --output，并在 stderr 上警告一次。请把脚本迁移到 --output。
  • --author 与 --author-mode 会映射到 --debug。

​
浏览器支持

start 没有 Safari 路径。传入 --browser safari（或 webkit-based）会以 E_COMMAND_UNSUPPORTED_FOR_TARGET 退出。这个结论是测量出来的：Safari 的 WebDriver 路径确实能加载一个未打包的目录，background 也确实会运行，但 Safari 给这个扩展的主机来源是零个。内容脚本永远不会注入，之后也没有任何 API 调用可以补上这个权限。Safari 目标请用 dev 或 build。

​
自动化元数据

start 会把就绪元数据写入：
  • dist/extension-js/<browser>/ready.json
在使用 --no-browser 时，这对自动化很有用：
  • 在启动外部 runner 之前等待 status: "ready"。
  • 把 status: "error" 当作确定性的失败信号处理。
  • 用 runId 与 startedAt 关联某次具体的运行时会话。

​
阻止浏览器启动

两个 flag 听起来很像，作用却不同：
--no-browser 还有配置写法 commands.start.noBrowser: true，以及环境变量写法 EXTENSION_CLI_NO_BROWSER=1。dev、start 和 preview 都接受这两个 flag。

​
--no-browser 与就绪同步

--no-browser 只会禁用浏览器启动。它并不会在生产构建完成之前阻塞外部 runner。 对于面向生产的 Playwright、持续集成（CI）和 AI 工作流：
  1. 把 extension start --no-browser 作为生产者进程。
  2. 把 extension start --wait --browser=<browser> 作为就绪闸门。
  3. 只有在 status: "ready" 之后才启动外部浏览器自动化。
--wait 在 error / 超时时以非零状态退出，并会忽略来自已死进程（pid 已不存在）的过期契约。 因为 start 可能很快就结束，所以只要时间戳落在 60 秒的窗口内，已完成运行留下的契约同样算数。 --wait 需要一个本地项目路径。传入远程 URL 会以 E_ARGS 退出。 在同一次调用中同时传入 --wait 与 --no-browser 会以 E_INVALID_OPTION 退出，因为 --wait 只读取另一个进程写出的契约。请像上面的步骤那样把它们作为两个进程运行。

​
用 --output json 输出机器可读结果

--output json 会在 stdout 上打印 schema-1 信封，每行一个 JSON 对象：
  • 普通的 start 运行会在构建完成、浏览器启动之后打印一个 status: "started" 帧。它带有项目路径、浏览器列表、pid 和 port: null，因为只运行不构建的会话不会绑定任何端口。失败的运行只打印它的失败帧，前面永远不会有 started 帧。
  • start --wait 运行成功时会打印一个 status: "ready" 帧。它的 value.results 数组按浏览器带出完整的就绪契约。
  • start --wait 读到处于 error 状态的契约时，会打印一个指明原因的 ok: false 帧，例如浏览器根本没有启动时的 E_BROWSER_LAUNCH，或浏览器退出时的 E_BROWSER_EXITED。完整列表见 ready.json 契约。
  • 构建失败时会打印一个 ok: false 帧，其中 status: "build-failed"，随后进程以 1 退出。编译错误带 error.code: "E_COMPILE"。项目目录不存在带 E_PROJECT_NOT_FOUND，目录里没有 manifest 带 E_MANIFEST_NOT_FOUND，manifest 无法解析带 E_MANIFEST_INVALID。配置文件加载失败带 E_CONFIG_LOAD，远程 URL 没有给出可用的归档带 E_REMOTE_ZIP_INVALID、E_REMOTE_FETCH_TIMEOUT 或 E_REMOTE_DOWNLOAD。
  • --chromium-binary 或 --gecko-binary 固定的二进制有问题时会打印一个 ok: false 帧，其中 status: "usage"，error.code: "E_BROWSER_BINARY_INVALID"。这包括路径不存在、文件不可执行，以及二进制在 10 秒内没有应答版本探测。命令随即结束，不会留下任何运行中的进程。
  • 浏览器无法启动时会打印一个 ok: false 帧，其中 status: "failed"。二进制文件可执行但系统无法启动它，或 Firefox 在调试器应答之前就退出时为 E_BROWSER_LAUNCH，Firefox 在运行但调试器始终没有应答时为 E_BROWSER_CONNECT。

​
日志 flag

这些 flag 是实验性的，可能在小版本之间发生变化。

​
共享的全局选项

也支持 全局 flag。

​
示例

​
用默认浏览器启动

​
在 Firefox 中启动

​
构建但跳过浏览器启动

​
行为说明

  • start 不会运行 dev 服务器，也不提供热模块替换（HMR）或 watch 模式。
  • start 面向生产模式；本地迭代开发请用 dev。
  • 对于机器消费者，请解析 dist/extension-js/<browser>/ready.json，而不是终端文本。

​
下一步

  • 用 dev 快速迭代。
  • 用 preview 启动已有的构建输出。