Midscene.js 浏览器自动化完整指南：3 步让 Chrome 听懂你的话-育师

Midscene.js 浏览器自动化完整指南：3 步让 Chrome 听懂你的话

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

你有没有遇到过这种场景：想在页面上自动点按钮、抓数据、验证流程，但写 Selenium 脚本要维护一堆选择器，改一次页面就崩一次？Midscene.js 的思路不一样——它用自然语言驱动浏览器自动化，你直接说"点击登录按钮"，它自己看截图、找元素、执行操作。这个仓库里的 Chrome 扩展就是最快的体验入口，不用搭项目，装好就能用。

🧭 它到底能做什么

Midscene.js 把浏览器自动化拆成三种指令，都写在同一句话里：

Action（操作）：点击、输入、滚动。比如type "Midscene.js" and click search。
Query（查询）：从页面提取结构化数据。比如页面中的商品，{name: string, price: number}[]，返回的是 JSON。
Assert（断言）：验证页面状态。比如页面顶部显示导航栏。

这三类能力在网页之外也都有对应实现，Android、iOS、HarmonyOS 和桌面端都有独立模块（见 apps/site/docs/zh/platforms/），本文以浏览器扩展为主线。

⚙️ 安装配置：三步跑通

第一步：装好扩展。优先从 Chrome Web Store 搜索安装 Midscene（可以自动更新）。如果你要改源码，可以克隆仓库后手动构建：

git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene/apps/chrome-extension pnpm run build

构建产物在dist目录。然后在chrome://extensions/打开开发者模式，点"加载已解压的扩展程序"，选中dist即可。

第二步：配置模型。扩展需要一个能理解界面的多模态模型，核心是四个配置项：MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY。把完整配置粘贴到扩展侧边栏的设置页并保存。支持豆包、千问、GLM、GPT 等多家模型，具体写法参考 apps/site/docs/zh/model-common-config.mdx。

第三步：发出第一条指令。打开任意网页，浏览器右侧会弹出 Midscene 侧边栏，切到 Action 标签，输入type "Midscene.js" and click search，点 Run。

📝 日常场景：三个可以直接抄的用法

自动填表：填写 GitHub 注册表单并通过表单校验，但不要提交——Midscene 会自己定位输入框、逐个填写并过校验，不会替你点提交。

批量抓数据：页面中的商品，{name: string, price: number}[]，Query 标签返回结构化 JSON，直接喂给下游脚本。

回归检查：页面顶部显示导航栏，且登录按钮可见，Assert 标签用来当轻量断言，比写选择器稳定得多。

跑完任何指令后，Midscene.js 都会在midscene_run/report/目录下生成 HTML 报告，每一步的截图、规划和耗时都能回放：

如果某条指令效果不理想，可以点侧边栏里的 "send to fullscreen playground" 切到全屏 Playground，里面有实时截图和更大的输入区，方便反复调试措辞：

🌉 进阶玩法：用 Bridge 模式控制你的真实浏览器

这是最实用也最容易被忽略的功能。前面扩展控制的是自己的标签页，而 Bridge 模式（桥接模式）让本地终端里的脚本直接接管你正在用的桌面 Chrome——已登录的状态、Cookie、扩展全部复用。想"自动操作但我已经登录着"的场景，就靠它。

使用步骤：

打开扩展的 Bridge Mode 面板，点 "Listening for connection"。扩展图标出现黄点表示监听中，绿点表示已连接。
模型配置注意：Bridge 模式下要写在终端环境变量里，不是浏览器侧。
Node 项目里安装依赖后，用AgentOverChromeBridge连接新标签页或当前标签页，运行脚本时浏览器会弹出确认窗，点Allow（或 Always Allow）即可放行。
如果脚本要上传本地文件，去chrome://extensions找到 Midscene，开启 "Allow access to file URLs"。

不想写代码也行，YAML 脚本里加一行bridgeMode: currentTab或bridgeMode: newTabWithUrl就能走桥接通道，完整写法见 apps/site/docs/zh/bridge-mode.mdx。

🛠️ 连接排错：四个高频坑

报错Cannot access a chrome-extension:// URL of different extension：基本是别的扩展往页面里注入了<script>或<iframe>造成的冲突。打开开发者工具，找到chrome-extension://开头的节点，复制扩展 ID，到chrome://extensions/里禁用它，刷新页面重试。
Ollama 本地模型报 403：设置环境变量OLLAMA_ORIGINS="*"，允许扩展访问本地模型服务。
Bridge 连不上：确认扩展面板显示 "Listening for connection"；默认地址是ws://localhost:3766，跨机器才需要改成远程地址；模型 Key 忘了配在终端侧是最常见的原因。
报告没生成：运行产物默认在midscene_run目录（report/放 HTML 报告、log/放日志），目录不对时可以用MIDSCENE_RUN_DIR环境变量改。更多问题可以看 apps/site/docs/zh/faq.md。