Skip to main content
浏览器扩展之所以难调试，是因为关键状态藏在你不易触及的地方：会进入空闲的 MV3 service worker、与页面隔离的 content script 世界、一失去焦点就关闭的 popup。Extension.js 在你的开发会话中开了一个小小的本地控制通道，让你（或者一个 AI agent，或者一个 CI 任务）能够直接访问这些上下文——读取它们打印的日志、检查它们渲染的内容、调用它们，并触发用户会触发的事件。 它运行在本地，不需要账号，观察始终是免费的。任何会改变状态的操作都需要按会话显式开启。

​
启用

启动一个开发会话时带上你需要的控制开关：
下面所有操作都指向这个会话，并以同样的方式定位上下文，无论是读取还是执行操作。

​
你可以做什么

extension logs 与 extension inspect 各自有独立的参考页：logs 与 inspect。

​
共享 flag

每个执行操作的命令都接受同样这三个 flag：
  • --browser 选择要指向的会话（默认 chromium）。
  • --timeout <ms> 限定一次往返的时长（默认 5000）。
  • --output <pretty|json> 选择 stdout 的输出方言。
当会话缺少所需的解锁开关时，拒绝信息会指明要用哪个 flag 重新启动：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 到底对页面做了什么：
默认输出就是值本身：字符串按原样打印，其他类型按缩进的 JSON 打印。当脚本需要读取结果时加上 --output json，你会得到完整的信封：
你的表达式触发的任何 console.log 都会同时通过 extension logs 输出，并按序号相关联——这样你能同时看到返回值和副作用。 如果要调用后台，请针对 Firefox 或 MV2 会话，那里的后台是一个可以正常求值的页面：
在 Chromium MV3 上（默认模板为 Chrome 构建的就是它），后台是一个 service worker，而 Chrome 的扩展 CSP 会在那里阻止 eval。在这类构建上，--context background 返回的是一条解释性错误而不是值。在 Chromium MV3 上请改用 --context page 或 --context content。extension.dev 的 MCP 服务器在 Chromium MV3 会话上对其 eval 工具应用同样的默认值。

​
跨浏览器支持

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 期间存在；它依赖一个不会出现在打包产物中的端口。

​
配合 AI agent

赞助 Extension.js 的平台 extension.dev 提供一个 MCP 服务器，把这些操作以工具的形式暴露给 agent。门控完全一致：助手可以自由地观察，但只有在你为本次会话启用后才能执行操作。参见 extension.dev MCP 服务器。

​
下一步

  • 触发动作和键盘命令——无需点击即可测试处理器，无头并可在 CI 中运行。
  • Manifest 拒绝——为什么 Chromium 会在会话还来不及连接之前就拒绝一个扩展。
  • Chrome DevTools MCP：Google 的 Chrome 调试服务器与 Extension.js 会话并用。
  • CI 模板——将这些能力接入 pull request 的检查。