跳转到主要内容
dev 是日常浏览器扩展开发的命令:watch 模式、启动浏览器,以及感知上下文的更新行为。 dev 会运行开发流水线并监听你的项目文件。它会根据变更类型采取不同的更新策略:热模块替换(HMR)、硬重载,或者当变更需要时进行完整重启。

什么时候使用 dev

  • 构建特性并实时验证改动。
  • 在一个或多个浏览器目标里调试扩展行为。
生产产物用 build;生产构建 + 启动用 start;只运行已有构建产物用 preview。 如果你的扩展放在 monorepo / 子模块里,请查看 extension.config.* 如何加载 env 文件(包括工作区根的回退):环境变量。

dev 命令的能力

什么会触发重新构建

watcher 跟随构建图:manifest 及其点名的一切、每个入口及其 import、pages/、scripts/ 与 public/ 文件夹、_locales/,以及项目配置与 env 文件。项目中其他任何位置的写入,例如 store/ 下的一张截图、一个演示页面、一份 README 或一个测试 fixture,都不会重新构建或重载扩展。在 dev 运行期间新建的特殊文件夹会在下一次编译时被纳入。 从 4.1.39 之后的版本起,位于符号链接文件夹下的项目只按一个路径被监视。在 macOS 上,第一次构建会在有限的时间内等待 watcher 完成首次扫描,然后才报告就绪,这样过早的保存不会被漏掉。 从 4.1.41 之后的版本起,构建有错误时,保存仍会重新构建页面。这包括页面本身以及它引用的每个文件。修复错误的那次保存会更新页面。dev 还会为新的语言文件夹、messages.json 旁边的新文件以及新的 _locales 文件夹重新构建。 从 4.1.41 之后的版本起,指向缺失文件的 CSS url() 或 require() 会被监视,所以创建该文件会重新构建会话。在 macOS 上,加入 public/ 的文件在整个会话中都会被输出。更早的版本在一次重新扫描恰好落在扫描进行中时,可能不再输出 public/ 中的新文件。 从 4.1.41 之后的版本开始,编译器的重启还会清理输出:
  • 当 manifest 的修改移除了一个入口时,重启会把该入口的文件从 dist/<browser> 中移除。
  • 在 pages/ 或 scripts/ 下删除或重命名文件,会让编译器自行重启,添加文件时本来就会这样。重启会移除已不存在的文件的输出。你不需要重启命令。

用法

CLI 不是全局安装的。npx extension@latest dev 会下载当前版本并运行它,所以单独的 extension 在你的 shell 里不是一个命令。在 create 生成的项目里,npm run dev 通过 package.json 的 dev 脚本运行同一个命令。
如果省略路径,Extension.js 会使用当前工作目录。你也可以传入一个 GitHub tree URL(例如 https://github.com/user/repo/tree/main/path)。Extension.js 会下载该仓库并在本地副本上以开发模式运行。

最常用的 flag

下面这些覆盖了 80% 的场景。其余的请跳到 完整参考。

参数与 flag

在 Firefox 上,--starting-url 会在附加组件安装完成后才打开,所以你的 document_start content script 会在该页面上运行。从 4.1.39 之后的版本起,它不再替换你的扩展自己打开的标签页。 有两个已废弃的别名从 --help 中隐藏,但仍然可用:
  • --wait-format <pretty|json> 映射到 --output,并在 stderr 上警告一次。请把脚本迁移到 --output。
  • --author 与 --author-mode 映射到 --debug。

Safari flag

这些 flag 只适用于 safari 与 webkit-based 目标。和其他目标一起传入其中任何一个都会以 E_INVALID_OPTION 退出,所以拼错不会静默地不生效。 对于 Safari 目标,dev 还会在第一次打包前运行工具链预检。缺少 Xcode 会以 E_SAFARI_TOOLCHAIN 快速失败。 从 4.1.20 起,Safari 会话就是一个完整的 dev 会话。你在 Safari 设置中启用扩展之后,extension logs 可以读取它,控制通道会连上,每次保存都会在 Safari 中重载扩展。详见 构建 Safari 扩展。

模拟的 Chromium

从 4.1.38 起,--browser=chromium-emulator 会在一个网页里的模拟 Chromium 中运行你的扩展,不需要设置任何 flag 或环境变量。dev 会输出这个页面的地址,并在你的默认浏览器中打开它。这个页面从你本机的 dev 服务器读取构建,所以只有 dev 能打开这个目标,start 与 preview 会拒绝它。 打开页面之前,dev 会先检查引擎的源(origin)是否有响应。源没有响应时,dev 会输出一条警告,并且什么都不打开:
dev 服务器会继续运行。--logs 对这个目标不起作用:扩展运行在网页中,所以请在那个页面上用你浏览器的开发者工具读取它的控制台。

父进程看门狗

--parent-pid 供派生 dev 的 harness 与 agent 使用,宿主崩溃不会泄漏服务器。它的值必须是正整数,其他任何值都会以 E_INVALID_OPTION 退出。看门狗每 2 秒轮询一次父进程。父进程消失后,dev 服务器会通过 SIGTERM 关闭;如果清理卡住,还有 5 秒的硬退出兜底。

端口如何确定

--port 是一个请求,而不是保证。请求的端口被占用时,dev 服务器会向上寻找最近的空闲端口。--port 0 会向 OS 要一个任意空闲端口。请从 ready.json 读取实际绑定的端口,而不是你传入的那个 flag。 --port 只设置 dev 服务器的端口。控制桥监听它自己的端口,没有任何 flag 能设置它。第一次运行时,会话向 OS 要一个空闲端口,并把它存进 .extension-js/control-port-<browser>。下一次运行会请求同一个端口,这样仍然记着旧端口的浏览器配置文件可以重新连上。这个端口被占用时,OS 会另行分配一个。请从 ready.json 的 controlPort 读取它。

dev 给你的扩展加了什么

dev 会话会给自己授予重载所需的东西,而同一份源码的生产构建里完全没有这些。从 4.1.39 之后的版本起,会话会在身份卡下方写明每一项:
  • Dev only 行列出只有 dev manifest 才有的权限、主机访问或 web accessible 资源。
  • 从 4.2.0 之后的版本起,以 manifest 开头的 Dev only 行列出 dev 构建改动过、而生产构建没有的其他 manifest 字段,比如 content_security_policy 'unsafe-eval'、externally_connectable.ids * 或 background.persistent true。
  • 从 4.2.0 之后的版本起,当 dev manifest 为每个 content script 写入一个 stub,并由后台 worker 注册真实文件以便修改能到达页面时,Chromium 会话会打印 Dev only manifest content_scripts.js dev stubs。isolated world 中的 document_start 分组保留它的静态条目。Firefox 没有 stub,也不会打印这一行。
  • Dev flag 行写明一个会改变你所见内容的启动 flag,以及能把它反过来的配置键。
  • Dev pref 行写明会话写进一个比会话活得更久的 profile 里的浏览器偏好。见浏览器偏好设置。
ready.json 在 devAdditions 下列出每一项及其原因。这些行里的东西都不会随扩展发布。运行 extension build 并阅读 dist/<browser>/manifest.json,就能看到商店实际收到的内容。

第一个页面会等待启动时的注册

background 脚本可以在启动时用 scripting.registerContentScripts 注册 content script。在这个调用应答之前加载的页面,永远不会运行被注册的脚本。 从 4.1.39 之后的版本起,dev 会按住第一个页面,直到 background 完成它的启动工作。这也包括在 await 过的调用(例如 fetch 或一次 storage 读取)之后才做的注册。等待的上限大约是五秒,所以页面一定会打开。 放在定时器后面的注册不会被等待。dev 无法知道 setTimeout 回调或 alarm 什么时候触发。 CLI 可能打印两行。等待超时时打印第一行:
注册在页面打开之后才到达时打印第二行:
两种情况下,如果脚本没有在页面上运行,请重新加载页面。被注册的脚本只会在注册之后加载的页面上运行。Firefox 仍可能在它正在打开的页面上运行脚本,所以请先确认再重新加载。 start 和 preview 以同样的方式按住第一个页面,等待 background 启动时或一次 storage 读取之后做的注册。它们不会等待放在 await 过的 fetch 或定时器后面的注册。对于这些注册,如果注册在最初 15 秒内到达,它们会打印第二行。

自动化元数据(推荐用于脚本 / agent)

dev 运行时,Extension.js 会向这些位置写入机器可读的元数据:
  • dist/extension-js/<browser>/ready.json
  • dist/extension-js/<browser>/events.ndjson(每行一个 JSON)
对于自动化(Playwright、持续集成(CI)、AI agent),请优先使用这些文件,而不是解析终端日志。 把 ready.json 当作就绪契约来用:
  • 启动期间 status: "starting"
  • 构建编译完成时 status: "ready"。从 4.1.39 之后的版本起,带 --allow-control 或 --allow-eval 并启动了浏览器时,ready 还会等待 background 连上,最多 10 秒。从 4.1.41 之后的版本开始,需要启动浏览器时,编译之后 status 仍保持 starting,等启动器盖上 browserPid、binary、profilePath 和调试器端口(Chromium 上是 cdpPort,Firefox 上是 rdpPort)之后才变为 ready。executorAttachedAt 可以出现在 ready 之后,除非会话是带 --allow-control 或 --allow-eval 启动的,这时 ready 会等它,最多 10 秒
  • 启动 / 编译失败时 status: "error",浏览器根本没有启动(code: "browser_launch_failed")或在扩展加载之前就退出(code: "browser_exited")时也是
  • 会话关闭后 status: "stopped",因此一个已经死掉的会话不会再宣称自己 ready
  • service worker 连接后为 runtime: "attached"(并带上 executorAttachedAt)。act verb 应该等待它,而不是等待 ready
  • 从 4.1.20 起,最后一个已连接的扩展上下文断开后为 runtime: "detached"(并带上 executorDetachedAt)。executorAttachedAt 会作为来源记录保留,重新连接后该值会回到 "attached"
  • runId 唯一标识一次运行时会话
  • startedAt 标记运行时会话的起始时间戳
  • command 记录产生它的命令(dev、start、preview 或 build)
  • toolchainVersion、extensionName 与 extensionVersion 记录是哪个 Extension.js 版本、为哪个扩展产出了这棵目录树——终端滚屏丢失后,这个文件仍是一份构建回执
  • port 是实际绑定的 dev 服务器端口,host 是客户端可以拨号的可连接主机(见绑定主机与可连接主机)
  • controlPort / instanceId 定位 extension logs 与 act verb 使用的控制桥
  • cdpPort(Chromium)与 rdpPort(Gecko)暴露浏览器调试端口。从 4.1.41 之后的版本开始,同时启动的会话各自拿到自己的调试端口,所以请读取这些字段,不要假定是 9222
  • profilePath、browserPid 与 extensionId 由浏览器启动器在启动后写入
完整的 schema、错误状态与两阶段就绪规则见 ready.json 契约。 events.ndjson 只属于当前这次运行:新一次运行开始时文件会重置,且每条记录都盖有本次运行的 runId(与 ready.json 一致),消费者不会看到上一个会话的事件与当前会话交错。 会话行为异常时,运行 extension doctor——它按顺序检查契约、控制通道、令牌、执行器与浏览器,并指出第一个失败的环节和修复方法。

阻止浏览器启动

两个 flag 听起来很像,作用却不同:
--no-browser 是无头、CI 与远程工作的运行模式,也是 Playwright E2E 工作流所依赖的 flag。它还有配置写法 commands.dev.noBrowser: true,以及环境变量写法 EXTENSION_CLI_NO_BROWSER=1。 --no-open 只是启动时的一个细节。当你希望浏览器停在它原本显示的页面上,而不让 Extension.js 在上面为你的扩展打开一个标签页时,就用它。dev、start 和 preview 都接受这两个 flag。

--no-browser 与就绪同步

--no-browser 只会禁用浏览器启动,但完整的 dev 循环仍然保留。dev 服务器依旧监听你的文件,并在每次重建后通过控制桥向扩展的 service worker 广播一次重载,因此即使没有被启动的浏览器在驱动,你的改动也会生效:
  • content script 的改动会就地重新注入到已经打开的匹配标签页(service worker 会用新的构建产物运行 chrome.scripting.executeScript),所以保存后页面就会更新,不需要手动刷新。之后新打开的标签页也会拿到新的构建产物,因为 service worker 会动态重新注册 content script(chrome.scripting.registerContentScripts)。
  • service worker / manifest 的改动会重启扩展。
所以在无头、持续集成(CI)以及远程 / dev container 工作流里,--no-browser 的表现和普通的 dev 会话一样:把构建好的 dist/<browser> 加载进任何你能控制的浏览器,它就会在你保存时持续更新。(如果你想要一个永不重载的静态 dev bundle,请用 --no-reload,见下文。) --no-browser 并不会在编译完成之前阻塞外部 runner。 对于 Playwright / CI / AI 工作流:
  1. 把 extension dev --no-browser 作为长期运行的进程。
  2. 把 extension dev --wait --browser=<browser> 作为就绪闸门。
  3. 只有在 status: "ready" 之后才启动外部浏览器自动化。
--wait 面向第二个进程(或 CI 步骤),在 error / 超时时以非零状态退出。 当 --wait 看到一个来自已死进程的过期 ready.json(pid 已不存在)时,它会继续等待一个活跃的生产者。 --wait 需要一个本地项目路径。传入远程 URL 会以 E_ARGS 退出。 在同一条命令中同时传入 --wait 与 --no-browser 会以 E_INVALID_OPTION 退出,因为 --wait 只读取另一个进程写出的契约。请像上面的步骤那样把它们作为两个进程运行。 从 4.1.21 开始,当 --wait 在生产者还在写入 ready.json 时读到它,会把这个写了一半的文件当作又一种暂态,继续轮询。到 4.1.20 为止,一次撕裂读取会让等待以 JSON 解析错误失败。始终无法解析的文件仍会以 E_READY_TIMEOUT 结束,超时消息会点明原因:The last read of the file failed to parse as JSON,后面跟着解析器自己的错误。

用 --output json 得到机器输出

--output json 会在 stdout 打印 schema-1 信封,每行一个 JSON 对象:
  • 普通的 dev 运行会在会话建立之后、紧接在 starting 帧之前,把一个 status: "started" 帧作为 stdout 的第一行打印出来。它带有项目路径、浏览器列表、请求的端口以及 dev 服务器的 pid。dev 不会自行结束,所以后面不会再有结果帧。随后的 生命周期帧(starting、compiled、ready 以及之后的帧)同样写到 stdout,给人看的进度行则写到 stderr,因此 stdout 的每一行都能按 JSON 解析。实时状态请读 ready.json。
  • 在会话建立之前就被拒绝的运行只打印一个 ok: false 帧,前面没有 started 帧。这包括缺少 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 固定的二进制有问题时,服务器不会停止。这包括路径不存在、文件不可执行,以及二进制在 10 秒内没有应答版本探测。契约进入 error,代码为 browser_launch_failed,并带有 browserLaunchFailedCode: "E_BROWSER_BINARY_INVALID"。失败帧带该 readyCode,其中 status: "usage",error.code: "E_BROWSER_BINARY_INVALID",对该会话运行的 dev --wait 也以同样的状态和代码作答。
  • 固定的二进制可执行但系统无法启动它时,服务器同样保持运行。失败帧的 status: "failed",error.code: "E_READY_ERROR_STATUS",readyCode 为 browser_launch_failed。
  • dev --wait 运行成功时会打印一个 status: "ready" 帧。它的 value.results 数组按浏览器给出完整的就绪契约。
  • 失败时会在进程以 1 退出之前打印一个带 error.code(例如 E_READY_TIMEOUT)的 ok: false 帧。处于 error 状态的契约会指明原因:固定的二进制被拒绝时是带 status: "usage" 的 E_BROWSER_BINARY_INVALID,浏览器根本没有启动时是 E_BROWSER_LAUNCH,在扩展加载之前就退出时是 E_BROWSER_EXITED,编译错误是 E_COMPILE。完整列表见 ready.json 契约。
  • 从 4.1.41 之后的版本开始,浏览器拒绝加载扩展时不会停止会话。流里会带一个 ok: false 帧,其中 status: "load-refused"、error.code: "E_EXTENSION_LOAD_REFUSED"。针对该会话的 dev --wait 会回答同样的状态和代码,并以 1 退出。会话会在下一次保存时重新尝试加载。见 Manifest 拒绝。
  • 从 4.1.41 之后的版本起,dev 仍在查找项目时的拒绝不会在 stderr 上打印任何内容。
  • 之后的失败,例如抛错的配置文件,还会在 stderr 上打印给人看的行。
  • 从 4.1.41 之后的版本起,无法构建的重启会发送一个 restart-failed 帧。
  • 之前的构建继续提供服务。见重启与关闭。
  • 每个会话的最后一帧是 stopped 或 failed。

--no-reload:得到一个干净的 dev bundle

--no-reload 会跳过 content script 重注入包装器与重建时的重载派发。dev 下的 dist 会更接近生产 bundle,文件变更时已打开的标签页也不会被打扰。你需要自己重载扩展或页面来看到改动。 --no-reload 仅在 extension dev 上受支持。把它传给 start、preview 或 build 会以错误退出。内部上它会设置 EXTENSION_NO_RELOAD=true,方便 develop 进程在 CLI argv 之外读取。 dev 构建会输出 cheap-module-source-map 类型的 source map,描述的是你的源码:原始的 TypeScript 与精确的行号,覆盖 content script、经典多文件分组、background 以及两个 manifest 版本下的页面。不会使用任何 eval 变体,因此 bundle 在你自己的 CSP 下运行。

日志 flag

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

共享的全局选项

也支持 全局 flag。

monorepo 与工作区根

你可以把 dev(以及 build)指向一个 monorepo 的根目录,而不是扩展包本身。Extension.js 会检测工作区根,并自动解析其中的扩展包:
如果只找到一个扩展包,Extension.js 会解析它并打印:
如果存在多个候选,会列出来让你指向具体那一个:

pnpm 工作区成员从根目录安装

从 4.1.18 开始,当项目是 pnpm 工作区的成员且依赖缺失时,自动安装会从工作区根目录运行,而不是从包目录运行。安装范围过滤为该成员及其工作区依赖:
锁文件和 linker 布局仍然属于工作区,所以结果与在根目录执行 pnpm install 一致。安装运行之前,会话会打印一行 info:

自动安装依赖

当 dev 或 build 发现项目依赖缺失时,会在编译之前安装它们。从 4.1.41 之后的版本起,只有项目自己的包管理器会运行这次安装。Extension.js 按以下顺序选定它:
  1. 项目根目录的锁文件:pnpm-lock.yaml、yarn.lock、bun.lockb、bun.lock,然后是 package-lock.json。
  2. package.json 中的 packageManager 字段。
  3. EXTENSION_JS_PACKAGE_MANAGER,或 EXTENSION_JS_PM_EXEC_PATH、npm_execpath 中的包管理器路径。
  4. Deno 项目:有 deno.lock,或有 deno.json、deno.jsonc 且旁边没有 package.json。
  5. 运行命令的那个包管理器,读取自 npm_config_user_agent 的第一个词。
  6. npm。
Extension.js 做这个选择时从不检查你的 PATH 上有哪些包管理器,所以同一个项目在每台机器上都选定同一个包管理器。选定的包管理器失败时,命令以 E_DEPENDENCY_INSTALL 停止。不会有别的包管理器代替它,因为那会生成一棵锁文件没有描述的依赖树。选定的包管理器没有安装时,消息会说明这一点,并告诉你如何安装它。

新版本到达 registry 期间的重试

一个新版本需要一两分钟才能到达整个 npm registry。从 4.1.41 之后的版本起,当失败是 registry 造成的时,安装会再运行一次:
  • registry 列出了某个版本,但还没有提供它的 tarball。
  • 依赖的依赖要求一个 registry 还没有列出的版本。
  • registry 返回 5xx 或 429 状态、重置连接、超时,或 DNS 查询失败。
你自己的项目声明的版本范围不会重试,因为只有你能修复它。认证错误(401 和 403)、磁盘和权限错误,以及 peer 依赖冲突也不会重试。 安装最多运行 4 次。两次尝试之间依次等待 5、10、20 秒,总共 35 秒。每次等待都会打印一条警告,说明原因和下一次尝试:
最后一次尝试也失败时,命令以 E_DEPENDENCY_INSTALL 停止:
如果是 registry 本身没有响应,第三行改为以 “The registry is having trouble answering right now.” 开头。

从不重试的拒绝

有两种失败会立即以 E_DEPENDENCY_INSTALL 停止安装。Extension.js 从不重试它们,也从不绕过它们。 版本太新。 pnpm 的 minimumReleaseAge 和 Deno 的最小依赖年龄会拒绝比限制更新的版本。消息会说明是哪条规则,如果包管理器打印了版本,也会给出该版本。要继续,可以等到版本足够旧,或固定到上一个版本。你也可以为这个包放宽规则:pnpm 把它加入 minimumReleaseAgeExclude,Deno 在 deno.json 中设置 minimumDependencyAge。 Corepack 无法下载包管理器。 包管理器根本没有启动。消息会给出 Corepack 请求的 registry,如果有 HTTP 状态也会给出。如果 Extension.js 是因为 npm_config_registry 或项目的 .npmrc 指定了该 registry 才选用它,消息也会说明。请检查该 registry 是否提供这个包管理器、你能否访问它,或者把 COREPACK_NPM_REGISTRY 设为一个能提供它的 registry。

示例

运行一个本地扩展

从 GitHub 运行一个远程扩展

把 GitHub tree URL 作为参数传入,即可在本地开发远程扩展:

在 Firefox 中运行

依次在多个浏览器中运行

在 Docker 或 dev container 中运行

当你在 Docker、dev container 或 GitHub Codespaces 中运行时,把 dev 服务器绑定到 0.0.0.0,宿主机才能访问到它:
搭配 --port 0 让 OS 自动选择一个可用端口:

绑定主机与可连接主机

--host 是 dev 服务器绑定的地址。浏览器(HMR 客户端与重载桥)需要的是一个它真正能连接的地址,两者并不总是同一个值:
  • --host 0.0.0.0 会绑定所有网络接口,但 0.0.0.0 并不是一个可连接的地址。Extension.js 会自动改为向浏览器公布 127.0.0.1,这正是常见的端口转发式 Docker / dev container / Codespaces 场景所需要的目标:浏览器跑在宿主机上,端口被转发到容器里。
  • 对于真正的远程场景(浏览器与 dev 服务器不在同一台机器上),请用 --public-host 传入浏览器能访问到的地址(局域网 IP 或主机名)。它会被传播到 HMR 客户端 URL、ready.json 以及烘焙进扩展里的重载桥。
当 --host 本身已经是一个具体地址时(例如 --host 192.168.1.50),这个值本来就可连接,会被直接使用。只有在绑定主机与浏览器面向的主机不同的时候,才需要 --public-host。 开发服务器会检查每个请求的 Host 头,作为对 DNS 重绑定的防御。它应答 localhost、IP 地址、绑定主机与 --public-host。用其他任何名字发来的请求都会得到 403,纯文本正文里写明被拒绝的主机和修复方法,终端上也会为每个被拒绝的主机打印一行。用 --allowed-hosts 放行更多名字,它是逗号分隔的列表,前导的点允许所有子域名,也可以写在 extension.config.js 的 commands.dev.allowedHosts 里(数组或逗号分隔的字符串)。当开发服务器是通过 docker 服务名、隧道主机名或 mDNS 名称被访问、而浏览器拨号的目标不该改变时,就用它。
单独的 --host 0.0.0.0 不会放行所有名字。绑定地址与放行的名字是两个独立的设置。

用 Brave 作为自定义二进制运行

最佳实践

  • 浏览器兼容性: 在不同浏览器中测试你的扩展,确保在每个目标上都能工作。
  • polyfill: dev 中 polyfill 默认关闭。Chromium 148 及更高版本原生提供 browser,所以只有面向更旧的版本时才需要传 --polyfill。在低于 152 的 Chromium 上,声明了 devtools_page 的扩展在任何脚本里都没有 browser 对象。参见跨浏览器兼容性。
  • 自动化可靠性: 把 dev 当作 watch 模式的伴侣(--no-browser + dev --wait);把 start 当作生产的伴侣(--no-browser + start --wait)。脚本与 CI 自动化使用 --output=json。

下一步