跳转到主要内容
启动一个已构建的扩展输出,进行类生产的手动测试。 preview 不会编译你的项目。它会加载一个已存在的未打包扩展根目录,并运行浏览器启动流程。

什么时候使用 preview

  • 想运行已有的构建输出,而不重新构建。
  • 快速对比已打包行为在多个浏览器目标上的表现。
  • 调试与生产产物相关、而非与 dev / watch 模式相关的运行时问题。

preview 命令的能力

preview 是 run-only 的。它会优先使用已存在的 dist/<browser>。你也可以让它指向其他已包含 manifest.json 的未打包扩展文件夹。

用法

如果省略路径,Extension.js 会使用当前工作目录。

preview 如何决定运行哪个目录

preview 按以下顺序检查:
  1. 你传入的 --output-path <dir>。它的优先级高于其他一切。
  2. 所选浏览器目标对应的 dist/<browser>。
  3. 提供的项目路径或当前工作目录。
该文件夹需要包含一个带 manifest.json 的未打包扩展。是否在同一条命令里跑过 build 并不重要。

参数与 flag

在 Firefox 上,--starting-url 会在附加组件安装完成后才打开,所以你的 document_start content script 会在该页面上运行。从 4.1.39 之后的版本起,它不再替换你的扩展自己打开的标签页。 --author 与 --author-mode 是 --debug 的隐藏、已废弃别名。

浏览器支持

preview 没有 Safari 路径。传入 --browser safari(或 webkit-based)会以 E_COMMAND_UNSUPPORTED_FOR_TARGET 退出。Safari 是受支持的浏览器,但这个命令无法启动它。这个结论是测量出来的:Safari 的 WebDriver 路径确实能加载一个未打包的目录,background 也确实会运行,但 Safari 给这个扩展的主机来源是零个。内容脚本永远不会注入,之后也没有任何 API 调用可以补上这个权限。Safari 目标请使用 dev 或 build。 preview 同样会拒绝 chromium-emulator,并以 E_UNSUPPORTED_BROWSER 退出。模拟的 Chromium 页面要从 dev 服务器读取你的构建,而 preview 不运行 dev 服务器。这个目标请使用 dev。

远程 URL 与 light 模式

当路径参数是一个远程 http(s) URL 时,preview 会自动设置 EXTJS_LIGHT=1。这会让下载下来的扩展以 light 模式启动。如果你事先自己设置了 EXTJS_LIGHT,则会覆盖这一行为。 在 --output json 下,下载进度行会写到 stderr,因此 stdout 只包含结果帧。

远程压缩包落在哪里

远程压缩包会被解压到你的缓存中,而不是你运行命令的文件夹。文件夹以 URL 路径命名,并附带一段短摘要,因此同一个压缩包总是落在同一个位置: 第二次运行同一个 URL 会直接复用这份副本而不再下载,并会说明这一点。删除该文件夹即可重新下载。URL 的查询字符串(分享 token 所在之处)不参与 key 的计算,也永远不会写到磁盘。 传入 --output-path <dir> 可以改为解压到你指定的文件夹。如果该文件夹已经存在,且不是从这个 URL 解压出来的,命令会以 E_DESTINATION_NOT_EMPTY 拒绝,并保持它原样不动。 从终端复制的链接如果被折行过,token 里可能夹带空格。preview 会去掉这些空格,并在下载前说明。服务器返回 401 或 403 时,会以 E_REMOTE_ACCESS_DENIED 报告为链接被拒绝,若 token 带有过期时间也会一并给出。

阻止浏览器启动

两个 flag 听起来很像,作用却不同:
--no-browser 还有配置写法 commands.preview.noBrowser: true,以及环境变量写法 EXTENSION_CLI_NO_BROWSER=1。dev、start 和 preview 都接受这两个 flag。 从 4.1.41 之后的版本起,当你传入 --browser 时,preview 和 start 中的 extension.config.js 会看到生产 env 文件以及所预览浏览器的文件,例如 .env.firefox。见环境变量。

自动化元数据

preview 会把就绪元数据写入:
  • dist/extension-js/<browser>/ready.json
没有项目包裹的文件夹(例如复制出来的构建文件夹)会把这些元数据保存在自身内部,位于 <folder>/dist/extension-js/。Extension.js 会加入一个说明该文件夹内容的 README.md,以及一个让它不进入提交的 .gitignore。 对于 --no-browser 流程,它提供了确定性的命令状态:
  • 命令初始化时为 starting
  • run-only 验证完成时为 ready
  • 缺少所需输出或启动失败时为 error
  • runId 与 startedAt 用于在脚本 / agent 中做会话关联
从 4.1.41 之后的版本开始,同时启动的会话各自拿到自己的调试端口。请从 ready.json 里读取 cdpPort 或 rdpPort,不要假定是 9222。卡片打印时,cdpPort 已经在记录里。 从 4.1.39 之后的版本起,带 --allow-control 或 --allow-eval 时,状态会保持 starting,直到扩展的 background 连上,或者过去 10 秒。要知道 act 命令能否运行,请读取 executorAttachedAt。见 ready.json 契约。 从 4.1.39 之后的版本起,这类会话给出的拒绝信息会把 extension preview 写成需要重启的命令。没有 background 脚本或 service worker 的构建无法被控制:会话在启动时会给出警告,每一个 act 命令都会回答这个构建没有 background。见 start 或 preview 会话上的拒绝。 会话结束之后,act 命令会如实说明,并打印重新启动它的 extension preview 命令。见 会话已经结束时。 preview 不提供 --wait 闸门 flag。preview 的自动化请直接消费 ready.json。

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

--output json 会在 stdout 打印一个 schema-1 信封:
  • 运行成功时打印一个 status: "ready" 帧。它的 value 携带项目路径以及被预览的浏览器列表。
  • 从 4.2.0 之后的版本起,ready 帧还带有 noBrowser。browsers 列出本次运行面向的浏览器,noBrowser: true 表示一个都没有启动,与 dev 和 start 的帧一致。
  • 从 4.2.0 之后的版本起,SIGINT 或 SIGTERM 会以一个带 E_INTERRUPTED、value.signal 和 value.browsers 的 stopped 帧结束流,运行以 0 退出。见 生命周期流。
  • 项目路径不存在时,会打印 ok: false,并带有 status: "usage" 与 error.code: "E_PROJECT_NOT_FOUND"。目录存在但没有 manifest 时,状态相同,代码为 E_MANIFEST_NOT_FOUND。这两种帧都不带提示。
  • 项目存在、但输出路径下没有未打包的扩展时,该帧为 ok: false,并带有 status: "not-found" 与 error.code: "E_PREVIEW_NO_DIST"。它的提示会让你先运行 extension build。
  • --chromium-binary 或 --gecko-binary 固定的二进制有问题时,会打印 ok: false,并带有 status: "usage" 与 error.code: "E_BROWSER_BINARY_INVALID"。这包括路径不存在、文件不可执行,以及二进制在 10 秒内没有应答版本探测。命令随即结束,不会留下任何运行中的进程。
  • 远程 URL 没有给出可用的归档时,会打印 ok: false 与 status: "failed"。返回的不是 ZIP 归档、归档已损坏或含有位于其文件夹之外的条目时代码为 E_REMOTE_ZIP_INVALID,超时为 E_REMOTE_FETCH_TIMEOUT,连接被拒绝或 HTTP 错误为 E_REMOTE_DOWNLOAD。
  • 浏览器无法启动时会打印 ok: false 与 status: "failed"。二进制文件可执行但系统无法启动它,或 Firefox 在调试器应答之前就退出时代码为 E_BROWSER_LAUNCH,Firefox 在运行但调试器始终没有应答时为 E_BROWSER_CONNECT。配置文件加载失败时以同样的状态打印 E_CONFIG_LOAD。
  • 从 4.1.41 之后的版本开始,浏览器拒绝加载扩展时会打印 ok: false,其中 status: "load-refused"、error.code: "E_EXTENSION_LOAD_REFUSED"。preview 会停止浏览器并以 1 退出。见 Manifest 拒绝。
  • 其他失败会打印 ok: false 与 status: "failed",随后进程以 1 退出。

日志 flag

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

共享的全局选项

也支持 全局 flag。

示例

预览一个本地扩展

在 Edge 与 Chrome 中预览

不启动浏览器进行预览

行为说明

  • preview 是 run-only 的,永远不会编译项目。
  • preview 优先使用已有的构建输出(dist/<browser>),但也可以回落到另一个未打包扩展根目录。
  • preview 不会运行 watch 模式,也不提供热模块替换(HMR)。
  • 从 4.1.41 之后的版本开始,如果浏览器拒绝这个扩展,preview 会停止浏览器并以退出码 1 退出。见 Manifest 拒绝。
  • 对于脚本 / agent,请依赖 ready.json,避免解析终端输出。

最佳实践

  • 测试新鲜的生产产物时,先跑 build 再跑 preview。
  • 当你的未打包扩展位于默认项目输出之外时,请传入项目路径参数。
  • 打包前用 --browser 在多个目标上验证行为。

下一步