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

​
启用

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

​
你可以做什么

​
指定上下文

读取和执行操作共享同一套词汇——你只需说明界面名称，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_eval MCP 工具正是出于这个原因，在 Chromium MV3 会话上默认使用 page 上下文；在 Firefox/MV2 上它的默认值仍然是 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_list_extensions 是 MCP 工具而不是 CLI 子命令——它通过 DevTools Protocol 连接，因此仅支持 Chromium。）

​
安全性

这些门控是有意为之，而不是官僚式的限制：
  • 观察无需任何开关。 读取日志和 DOM 始终可用。
  • 有边界的操作需要 --allow-control。 storage、reload 与 open 会改变状态，因此你需要按会话主动开启。
  • eval 需要 --allow-eval 以及一个按会话生成的 token。 该 token 写入 dist/ 之外的一个 0600 文件中，因此绝不会随构建产物发出——本地随机进程无法悄悄驱动你的 service worker。
  • 任何东西都不会进入生产环境。 控制通道只在 dev / preview 期间存在；它依赖一个不会出现在打包产物中的端口。

​
配合 AI agent

同样这些操作通过 @extension.dev/mcp 以 MCP 工具的形式暴露出来（extension_logs、extension_eval、extension_storage、extension_reload、extension_open、extension_list_extensions）。门控完全一致——助手可以自由地观察，但只有在你为本次会话启用后才能执行操作。

​
下一步