启用
启动一个开发会话时带上你需要的控制开关:你可以做什么
extension logs 与 extension inspect 各自有独立的参考页:logs 与 inspect。
共享 flag
每个执行操作的命令都接受同样这三个 flag:--browser选择要指向的会话(默认chromium)。--timeout <ms>限定一次往返的时长(默认 5000)。--output <pretty|json>选择 stdout 的输出方言。
eval 对应 --allow-eval,其余全部对应 --allow-control。你不用去猜自己漏了哪个门控。
哪些内容会落到磁盘上
除了实时通道之外,会话还会在dist/extension-js/<browser>/ 下写入只追加的记录:logs.ndjson 保存捕获到的每一条日志事件,actions.ndjson(在会话带 --allow-control 时写入)审计已执行的控制操作。两者在会话结束后仍可读取。
日志契约还预留了结构化的 dx.signal 条目,它们是关于运行时自身健康状况的机器可读诊断信息,过滤方式为 extension logs --signals-only。目前还没有任何发射端,因此这个过滤器现在什么也不会返回。它的结构已经先行文档化,这样等第一条 signal 落地时,消费方就可以据此分支。
指定上下文
读取和执行操作共享同一套词汇——你只需说明界面名称,Extension.js 会根据它正在跟踪的会话进行解析。示例:我的扩展真的改动了页面吗?
这个例子在默认模板上可以直接运行。--context page 在当前标签页的 MAIN 世界中求值,因此你可以检查 content script 到底对页面做了什么:
--output json,你会得到完整的信封:
console.log 都会同时通过 extension logs 输出,并按序号相关联——这样你能同时看到返回值和副作用。
如果要调用后台,请针对 Firefox 或 MV2 会话,那里的后台是一个可以正常求值的页面:
--context background 返回的是一条解释性错误而不是值。在 Chromium MV3 上请改用 --context page 或 --context content。extension.dev 的 MCP 服务器在 Chromium MV3 会话上对其 eval 工具应用同样的默认值。
会话已经结束时
从 4.1.39 之后的版本起,act 命令或logs --follow 在连接之前,会先确认所选浏览器的会话仍在运行。会话结束后,ready.json 文件仍然留在磁盘上,所以单凭这个文件并不能证明有会话在运行。你用 Ctrl+C 停止了会话(文件里会留下 status: "stopped"),或者它的进程已经不在、控制端口也无人应答,都算会话已经结束。
这时命令会以退出码 1 和 E_SESSION_NOT_FOUND 退出。消息会说明会话已经结束,给出原因,并打印重新启动它的命令。这条命令是 extension dev、extension start 或 extension preview,取决于当初是哪一个启动了会话:
eval 是 --allow-eval,其他 act 命令是 --allow-control,logs --follow 则不带 flag。
如果同一个项目里另一个浏览器的会话正在运行,消息末尾会带一条提示:
ready.json 不会触发它。某个浏览器根本没有 ready.json 时,拒绝信息后面也会跟着同样的提示。
start 或 preview 会话上的拒绝
从 4.1.39 之后的版本起,由extension start 或 extension preview 带 --allow-control 或 --allow-eval 打开的会话,会在每一条拒绝信息里写出它自己的命令。dev 会话说 restart the dev session 的地方,这类会话说的是 restart the extension start session 或 restart the extension preview session。例如,在没有 --allow-eval 的 preview 会话上运行 eval,得到的回答是:
E_CONTROL_UNAVAILABLE 失败,并说明这个构建没有 background:
跨浏览器支持
Extension.js 通过浏览器内伴侣进程进行调试,而不是 Chrome DevTools Protocol,因此核心循环可以在 Chrome 与 Firefox 上都到达你自己的界面——曾经那堵“Firefox 用 RDP,所以不支持”的墙在这些工具上已经不存在了。
(在 Chromium MV3 构建上,
eval --context background 返回的是一条解释性错误。MV3 的后台是 service worker,而 Chrome 的扩展 CSP 在每个 MV3 构建上都拒绝 unsafe-eval,不只是生产环境。在 Chromium MV3 上请在 page / content 中求值,或者针对 Firefox/MV2 构建调用后台。)
日志在浏览器里的位置
extension logs 把每个上下文合并进同一条终端时间线(见 logs)。当你想看某个上下文在浏览器自己的控制台里的输出时,每个上下文都在不同的门后面:
三个细节能帮你省时间:
- 在 Chrome 上,service worker 链接还能唤醒一个空闲的 MV3 worker,当后台看起来没反应时用它。
- Content script 的日志永远不会出现在扩展自己的检查器里。在页面 DevTools 的控制台中,上下文下拉框可以过滤到你的扩展的隔离世界。
- 在 Firefox 上,
about:debugging工具箱覆盖后台和扩展页面。Content script 的输出留在页面的 DevTools 里。
extension logs,按上下文打标签,不需要点开任何一扇门。
安全性
这些门控是有意为之,而不是官僚式的限制:- 在你自己的机器上,观察无需任何开关。 读取日志和 DOM 始终可用。从另一台机器连接的客户端必须出示会话令牌。
- 有边界的操作需要
--allow-control。storage、reload与open会改变状态,因此你需要按会话主动开启。 eval需要--allow-eval以及一个按会话生成的 token。 该 token 写入dist/之外的一个0600文件中,因此绝不会随构建产物发出——本地随机进程无法悄悄驱动你的 service worker。- 网页无法连接。 控制 socket 会拒绝带有网页来源(
http://、https://或null)的握手,因此浏览器中打开的网站无法访问它。 - 任何东西都不会进入生产环境。 控制通道只在
dev/preview期间存在;它依赖一个不会出现在打包产物中的端口。
会话在浏览器里触及什么
开发浏览器会打开一个仅供 Extension.js 进程使用的远程调试端口。会话通过它只附加到你扩展自己的目标:后台 worker,以及在--logs 下的 popup、options 和 sidebar 页面。它从不附加到网站的页面或 service worker,所以网站打开的弹窗(例如登录窗口)在你调试时照常工作。
有些网站仍会把任何带调试端口的浏览器视为自动化。即使是真人操作,长按验证等机器人检查在开发浏览器里也可能永远通不过。要测试这类流程,请运行 extension build,然后在 chrome://extensions 开启开发者模式,把 dist/<browser> 加载到你日常使用的浏览器里。
配合 AI agent
赞助 Extension.js 的平台 extension.dev 提供一个 MCP 服务器,把这些操作以工具的形式暴露给 agent。门控完全一致:助手可以自由地观察,但只有在你为本次会话启用后才能执行操作。参见 extension.dev MCP 服务器。下一步
- 触发动作和键盘命令——无需点击即可测试处理器,无头并可在 CI 中运行。
- Manifest 拒绝——为什么 Chromium 会在会话还来不及连接之前就拒绝一个扩展。
- Chrome DevTools MCP:Google 的 Chrome 调试服务器与 Extension.js 会话并用。
- CI 模板——将这些能力接入 pull request 的检查。

