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 脚本运行同一个命令。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 会输出一条警告,并且什么都不打开:
--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 onlymanifest 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 可能打印两行。等待超时时打印第一行:
start 和 preview 以同样的方式按住第一个页面,等待 background 启动时或一次 storage 读取之后做的注册。它们不会等待放在 await 过的 fetch 或定时器后面的注册。对于这些注册,如果注册在最初 15 秒内到达,它们会打印第二行。
自动化元数据(推荐用于脚本 / agent)
dev 运行时,Extension.js 会向这些位置写入机器可读的元数据:
dist/extension-js/<browser>/ready.jsondist/extension-js/<browser>/events.ndjson(每行一个 JSON)
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 之后的版本开始,同时启动的会话各自拿到自己的调试端口,所以请读取这些字段,不要假定是 9222profilePath、browserPid与extensionId由浏览器启动器在启动后写入
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 的改动会重启扩展。
--no-browser 的表现和普通的 dev 会话一样:把构建好的 dist/<browser> 加载进任何你能控制的浏览器,它就会在你保存时持续更新。(如果你想要一个永不重载的静态 dev bundle,请用 --no-reload,见下文。)
--no-browser 并不会在编译完成之前阻塞外部 runner。
对于 Playwright / CI / AI 工作流:
- 把
extension dev --no-browser作为长期运行的进程。 - 把
extension dev --wait --browser=<browser>作为就绪闸门。 - 只有在
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 会检测工作区根,并自动解析其中的扩展包:
pnpm 工作区成员从根目录安装
从 4.1.18 开始,当项目是 pnpm 工作区的成员且依赖缺失时,自动安装会从工作区根目录运行,而不是从包目录运行。安装范围过滤为该成员及其工作区依赖:pnpm install 一致。安装运行之前,会话会打印一行 info:
自动安装依赖
当dev 或 build 发现项目依赖缺失时,会在编译之前安装它们。从 4.1.41 之后的版本起,只有项目自己的包管理器会运行这次安装。Extension.js 按以下顺序选定它:
- 项目根目录的锁文件:
pnpm-lock.yaml、yarn.lock、bun.lockb、bun.lock,然后是package-lock.json。 package.json中的packageManager字段。EXTENSION_JS_PACKAGE_MANAGER,或EXTENSION_JS_PM_EXEC_PATH、npm_execpath中的包管理器路径。- Deno 项目:有
deno.lock,或有deno.json、deno.jsonc且旁边没有package.json。 - 运行命令的那个包管理器,读取自
npm_config_user_agent的第一个词。 - npm。
PATH 上有哪些包管理器,所以同一个项目在每台机器上都选定同一个包管理器。选定的包管理器失败时,命令以 E_DEPENDENCY_INSTALL 停止。不会有别的包管理器代替它,因为那会生成一棵锁文件没有描述的依赖树。选定的包管理器没有安装时,消息会说明这一点,并告诉你如何安装它。
新版本到达 registry 期间的重试
一个新版本需要一两分钟才能到达整个 npm registry。从 4.1.41 之后的版本起,当失败是 registry 造成的时,安装会再运行一次:- registry 列出了某个版本,但还没有提供它的 tarball。
- 依赖的依赖要求一个 registry 还没有列出的版本。
- registry 返回 5xx 或 429 状态、重置连接、超时,或 DNS 查询失败。
E_DEPENDENCY_INSTALL 停止:
从不重试的拒绝
有两种失败会立即以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。
下一步
- 用
build构建生产产物。 - 用
start验证生产启动流。 - 在 按浏览器划分的 manifest 字段 中查看浏览器目标设置。
- 在
extension.config.js中集中配置共享默认值。 - 在 环境变量 中查看配置期 env 加载行为。

