Midscene.js实战：自然语言驱动Web自动化，从安装配置到跑通首个用例

1. 从元素定位到自然语言：为什么我盯上了 Midscene.js

做 Web 自动化和 UI 测试的同学，过去几年应该没少被元素定位折磨。xpath 写得又臭又长，css selector 稍微改个 class 就凉了，更别说现在前端框架天天迭代，组件库一升级，原来跑得好好的脚本直接大面积报错。我上一份工作里，每天大概有三分之一的时间在维护老的自动化用例，改完这个元素的定位，另一个又崩了，说实话挺崩溃的。

后来看到豆包团队相关的开源项目 Midscene.js，主打的就是通过自然语言驱动 Web 自动化，等于直接把传统那套“找元素、做操作、写断言”的模式换掉了。你不需要再去纠结#main-content > div.card:nth-child(2)这种字符串是从哪复制出来的，只需要说一句人话，比如“点击页面上的搜索框，输入小米手机，然后点搜索”，Midscene.js 自己会去理解页面结构、定位目标、执行操作。

这听起来确实像在做梦，但实际是可行的。它的底层思路是让大模型去理解页面的视觉和 DOM 结构，再转换成具体的操作指令，而不是靠固定路径去锁定元素。测试脚本的健壮性、可维护性和编写速度，都会有一次挺明显的提升。这篇主要是安装配置篇，我先把环境搭建和初始配置讲清楚，后面有机会再分享具体写用例的经验和踩坑记录。

这篇文章适合谁看？适合已经被传统 UI 自动化维护成本折磨过的测试开发工程师，适合想用 AI 能力批量生成 Web 操作脚本的前端同学，也适合产品、运营这类非技术岗位想自己跑通浏览器自动化流程的人群。

2. 环境准备：别急着装，先把机器搞干净

2.1 Node.js 和 Python 的版本要求

Midscene.js 是一个基于 JavaScript 生态的工具，所以 Node.js 是必须的。我建议装 Node.js 18 以上版本，最好直接用最新 LTS，实测在 Node 16 上跑会有兼容提示，虽然能勉强运行，但连接浏览器的过程中偶发超时，没必要踩这个坑。

安装完之后在终端里验证一下：

node -v npm -v

只要这两条命令能正常输出版本号，Node 环境就算过了。如果你机器上已经装了 nvm 或 fnm 这类版本管理工具，记得切换到一个干净的 Node 版本再继续，避免和老项目依赖打架。

Python 这边需要装 3.9 以上版本，但严格来说它并不是运行 Midscene.js 的硬性要求。你可能会问，那为什么还要提 Python？因为我后续计划配合一些 AI 辅助脚本做批量回归场景，而且部分浏览器控制工具在 Python 环境里有一种更顺手的调用方式，提前把 Python 环境准备好，后面扩展功能的时候不用再来回切环境。

装好后同样验证一下：

python3 --version

2.2 浏览器选择：Chrome 还是 Chromium

Midscene.js 的核心能力是通过浏览器调试协议去驱动浏览器动作，所以你需要一个能稳定对接的浏览器。Chrome 和基于 Chromium 内核的 Edge 是最稳妥的选择，因为它们对调试协议的支持比较完善。

实际测试中，我用的是 Chrome，因为它的远程调试接口最稳定，出现问题的时候排查资料也最多。在 Windows 上需要留意浏览器自动更新的位置，在 macOS 上则要注意允许终端应用进行控制，这两个是新手最容易卡住的环节。

2.3 豆包 API Key：没有它模型不会干活

Midscene.js 虽然本身是开源工具，但自然语言转操作指令这件事，背后需要大模型来支撑。豆包是目前我测试下来速度、中文理解能力都挺均衡的一个选择，关键是它和 Midscene.js 的适配也足够顺畅。

去豆包的开发者平台注册账号，创建一个应用之后就能拿到 API Key。注意这个 Key 是敏感信息，不要随便提交到 Git 仓库或者分享给别人，一旦泄露立刻去平台侧轮换掉。拿到 Key 之后把它配置到环境变量里，这样在使用 Midscene.js 的时候，连接器会自动读取。

先提前说一句：Midscene.js 支持的模型不止豆包一个，但在我写这篇安装配置篇的时候，主流方案是走豆包的接口。如果你用的是其他兼容接口，只要在配置上把地址和模型名对齐，也是一条可行的路线。

3. Midscene.js 安装：从零到跑通的最短路径

3.1 用 npm 安装核心依赖

安装过程本身不复杂，但“不复杂”和“不踩坑”是两码事。我建议在一个全新的目录里操作，不要把公司老项目和其他工具混在一起。

mkdir midscene-demo cd midscene-demo npm init -y npm install midscene

第一条npm init -y会生成一个默认的 package.json，后面安装的依赖都会集中管理在这里。npm install midscene会把 Midscene.js 主包拉下来，这是整个工具的核心。

如果你对 Playwright 或 Puppeteer 已经比较熟悉，会发现 Midscene.js 的设计思路和它们很像，但也有关键区别：它底层确实整合了浏览器控制能力，但你在写用例的时候，不需要直接面对那些细粒度的浏览器 API，自然语言描述直接就能变成动作序列。

安装完之后检查一下：

npm list midscene

能列出 midscene 的版本号就说明装上了。如果这里出现 EACCES 权限错误，通常是 npm 全局目录权限的问题，用 nvm 重装 Node 往往能一并解决。

3.2 安装浏览器调试辅助件

Midscene.js 主包安装好之后，还需要让浏览器能够被它正确识别和驱动。这里有两种选择：一种是使用 Playwright 的浏览器管理能力，另一种是直连已经打开的 Chrome。

npm install playwright npx playwright install chromium

第一条命令装的是 Playwright 这个自动化库，第二条命令会下载一个独立的 Chromium 内核。这个内核的好处是跟系统里你自己装的 Chrome 完全隔离，版本由 Playwright 自己管理，测试环境干净、可重现，不会被日常使用的浏览器配置干扰。

如果你不想额外下载一个浏览器内核，也可以走“直连自己常用浏览器”的方案，这在后面的配置文件里会体现。两种方案的区别，我会在配置那一节详细讲。

3.3 环境变量配置：不要硬编码密钥

很多新手图省事，直接把 API Key 写在代码里，然后代码一提交到仓库，Key 就全公司可见了。这种事我见过不止一次，关键是出事了不仅丢人，还得花时间处理密钥轮换和后续的权限排查。

正确做法是配置环境变量。在 macOS 或 Linux 下：

export MIDSCENE_API_KEY="你的豆包API Key" export MIDSCENE_MODEL_NAME="doubao"

在 Windows PowerShell 下：

$env:MIDSCENE_API_KEY="你的豆包API Key" $env:MIDSCENE_MODEL_NAME="doubao"

每次打开终端都要重新 setenv，挺麻烦的。我建议顺便在项目根目录下建一个.env文件，把变量写进去，然后在启动脚本里加载。Node.js 项目里可以用dotenv这个库来读取：

npm install dotenv

加载方式是在你的入口文件最顶部加一行：

require('dotenv').config()

这样环境变量会从.env文件里自动读进来。注意.env文件本身一定要加进.gitignore，切记。

4. 配置浏览器连接方式：两种方案，按需选择

4.1 方案一：Playwright 托管浏览器

这种方式适合大多数人，尤其是你追求开箱即用的体验。Midscene.js 会通过 Playwright 启动一个受控的 Chromium 进程，脚本跑完浏览器自动关闭，不污染你日常浏览会话。优点是环境隔离干净，缺点是如果你需要调试页面视觉效果，不方便进行交互式检查。

示例代码如下：

import { Agent } from 'midscene' import { PlaywrightConnect } from 'midscene' const agent = new Agent({ connect: new PlaywrightConnect({ browserType: 'chromium', }), mode: 'natural-language', })

这里browserType支持chromium、firefox、webkit，但我建议你老老实实用 chromium，因为 WebKit 的兼容性几轮版本下来都还有小毛病，而 Firefox 在自然语言指令转换为视觉效果时的截图解析偶尔会有延迟。Chromium 在性能、解析准确率和稳定性上目前是最平衡的。

4.2 方案二：直连本机已打开的 Chrome

这种方案更适合你在开发阶段希望边看边改，或者你需要在已经登录态的浏览器里面执行操作。比如你要测试一个已经登录后台的页面，如果每次都由 Playwright 启动一个全新浏览器，登录态就没了，你还得额外写一套登录逻辑，非常烦。

直连已经打开的 Chrome，需要你先以调试模式启动浏览器。在启动 Chrome 之前，先关掉所有 Chrome 进程，然后执行：

# macOS /Applications/Google Chrome.app/Contents/MacOS/Google Chrome --remote-debugging-port=9222 # Windows C:\Program Files\Google\Chrome\Application\chrome.exe --remote-debugging-port=9222

然后 Midscene.js 通过这个调试端口去接管浏览器的行为。示例代码：

import { Agent } from 'midscene' import { BrowserConnect } from 'midscene' const agent = new Agent({ connect: new BrowserConnect({ port: 9222, }), mode: 'natural-language', })

走这种方式时你可以在浏览器里面自由操作，甚至开多个标签页，Midscene.js 只对当前激活的标签页执行指令。

4.3 两种方式的选型建议

我结合自己的实际使用经验说一下选型依据：跑回归测试和平时写独立用例，建议优先用 Playwright 托管方式；但如果你是在做日常页面测试、需要人工多看几眼交互细节，或者遇到需要登录态的页面，建议直连本机 Chrome。这两种方式之间切换非常方便，只需改一下 connect 的配置就行。

5. 跑通第一条自然语言用例

5.1 最小的自动化脚本

环境都配好之后，我们来写一个最小的自动化脚本。这个脚本的作用是打开一个网页，用自然语言执行一个搜索操作，然后输出页面标题。我拿公开的某搜索引擎页面举例，你换成别的页面也没问题。

const { Agent } = require('midscene') const { PlaywrightConnect } = require('midscene') require('dotenv').config() async function main() { const agent = new Agent({ connect: new PlaywrightConnect({ browserType: 'chromium', headless: false, }), mode: 'natural-language', }) await agent.goto('https://www.baidu.com') await agent.ai('在输入框中输入 自动化测试 并点击搜索按钮') const title = await agent.getCurrentPageInfo() console.log(title.title) } main()

这里headless: false表示浏览器以有头模式运行，你能看到它实际操作的过程。如果你希望跑批处理、不弹窗，可以把headless改成true。

到这一步你会发现，全程代码量非常少，没有任何document.querySelector或者page.click('#search')这类操作，你只需要把“我要做什么”告诉它就行。

5.2 理解“自然语言指令”的执行链路

上述agent.ai是一个很神奇但也可能很抽象的方法。你可能会好奇，它到底是怎么理解一句话并去页面上找元素的？简单说，它会把当前页面的截图和 DOM 结构发到豆包模型，模型返回一个结构化操作序列，比如[{action: 'input', content: '自动化测试', target: '搜索框'}, {action: 'click', target: '搜索按钮'}]，然后 Midscene.js 再把这些结构化操作翻译成真实的浏览器动作。

换句话说，自然语言只是你对外沟通的接口，真正的执行链路还是“视觉理解 + 结构化动作”。理解这一点很重要，因为这意味着你给出的指令越贴近页面的视觉特征，模型定位就越准确。你自己心里要有一个映射逻辑：指令里的文本，要能在页面上直接找到对应内容。

5.3 执行结果和断言

脚本跑完之后，除了看浏览器里有没有正常操作之外，更重要的是对结果做断言。在传统测试框架中，你要写很长一串expect(selector).toHaveText(...)，而 Midscene.js 允许你直接用自然语言去断言：

const result = await agent.aiEvaluate('页面上是否出现了 搜索结果 相关的文字，如果有请总结第一条搜索结果的标题') console.log(result)

这段代码会交给模型去判断页面内容，并返回你想要的信息。它等于把“读取页面数据”和“判断结果是否符合预期”这两步合并到了一步。

我跑下来整体体验是，这条链路在一般的中文网页上表现很稳，模型对中文文字的理解度明显比传统正则、关键字匹配聪明太多。

6. 常见问题与排查技巧实录

6.1 安装时报错和依赖冲突

安装阶段遇到最多的问题是权限报错或者版本冲突。如果你用了公司的私有 npm 源，注意私有源上 midscene 版本可能更新不及时，导致拉到的是旧版本，从而出现Agent这个类未导出的报错。

解决办法有两个方向：一是临时切换到 npm 官方源重新安装，二是检查 package.json 里 midscene 版本号是否为最新版本。

npm install midscene@latest

还有一个典型问题是和 Puppeteer 或 Playwright 高版本一起装时会出现browserType冲突。这种情况大多是因为不同包对/usr/bin/chromium或 Chrome 路径的寻找顺序不一样。最简单的排查方式就是全部重装依赖：

rm -rf node_modules package-lock.json npm install

注意：package-lock.json如果删掉再安装，版本会重新解析，有可能会带来新的变化，但通常也是解决依赖混乱最彻底的手段。

6.2 API Key 相关：认证失败或额度不足

如果你遇到认证失败，优先检查环境变量是否真的被读取到了。可以在代码里打印一下process.env.MIDSCENE_API_KEY看是否有值。如果.env文件在.gitignore之外，或者没有通过 dotenv 加载，环境变量确实读不到。

额度不足的问题我在实际测试中也遇到过。豆包接口默认有一些免费的调用配额，一旦用完就会返回 429 或者类似提示。这种情况下没有别的花招，去开发者平台看一下配额情况，等次日重置或者充值。

值得提醒的是：自然语言驱动 UI 自动化这种方式，消耗的 token 比传统脚本要高不少，因为它需要把页面截图和 DOM 结构都发给模型。如果你在跑大型回归用例集，务必评估一下 API 调用量的成本，不然月底账单出来会有点疼。

6.3 浏览器连接失败和超时

直连 Chrome 最常见的坑是忘记关掉已经运行中的 Chrome 进程，直接执行带调试端口的启动命令。你会发现新开的命令没有效果，页面也连不上。正确的做法是：先把所有 Chrome 窗口全部关闭，再执行带--remote-debugging-port=9222的启动命令。

如果仍然失败，检查端口是否被占用：

lsof -i :9222

有这条输出才说明调试端口真的起来了。没有输出就说明 Chrome 没把调试接口打开，大概率是启动命令没生效。

Playwright 托管模式下遇到启动超时，可以去检查 Chromium 内核是否已经成功下载。在国内网络环境下，npx playwright install chromium有可能下载失败，这种情况可以换个镜像源再试，但要注意合规问题，尽量走正规渠道。

6.4 自然语言指令执行结果不稳定

最后这个问题，可能是自然语言驱动方式最需要心理准备的一点：模型的理解偶尔会有偏差，同样一句话，这次跑和下次跑，理论上有微小概率选出不同的元素。

我在实操中总结了一些提高稳定性的经验。一是指令描述要尽量具体，避免歧义。比如“点一下那个蓝色的按钮”就不如“点击页面右上角的‘立即购买’按钮”稳定。二是如果页面上有多个相似元素，在指令里加入位置描述，比如“左侧列表中的第二个选项”。三是关键流程执行完后，建议通过aiEvaluate做一次结果确认，确保动作真的生效。

另外，Midscene.js 有一个录制插件，也就是 Recorder，可以帮助你通过浏览器交互记录操作过程，再导出自然语言脚本。这个工具对快速生成用例非常有帮助，我建议你在安装配置完成后就去体验一下。录制过程中你的点击、输入、跳转都会被记录下来，生成的脚本再手工微调一下，效率会很高。

7. 关于豆包与 Midscene.js 搭配的几点心得

7.1 为什么选择豆包这个模型

Midscene.js 在设计上可以接入多种大模型，不强制绑定某个服务商。但我测试下来，豆包的接口稳定性和响应速度给我留下的印象最深。特别是中文长句的理解能力，在常见网页场景下几乎没有歧义理解错误。配置上也比较简单，模型名直接写doubao即可，不需要去查一堆别名。

你可以根据自己的使用场景去尝试其他模型，但我建议在入门阶段先用豆包把整个链路跑通，之后再逐步去对比不同模型在实际用例上的表现差异，这样不容易被多个变量的干扰带偏。

7.2 自然语言 UI 自动化的适用边界

我必须诚实指出，自然语言驱动 UI 自动化并不是银弹。它特别适合页面结构频繁变化、逻辑复杂但文案稳定的业务系统，比如后台管理系统、运营平台、数据报表系统等。但如果是那种大量动态渲染、无稳定文字标签、纯粹靠图形视觉交互的页面，模型的理解成本就会升高，不如传统方式可控。

这也是我为什么在标题里说“全新体验”而不是“全面替代”——它带来的是编写和维护体验上的跃升，但在断言严谨性和执行可重复性上，仍然需要你设计合理的校验策略来把关。

8. 最后分享一个配置小技巧

配置完整个环境之后，我建议你把这些依赖和配置整理成一个模板项目，推到一个固定的代码仓库。这样下次在新电脑或者新同事那搭环境，几行命令就能复制出一套可用环境来，不用重新踩一遍配置坑。

我自己的模板项目结构大致如下：

midscene-demo/ ├── .env # 环境变量（包含API Key，不进Git） ├── .gitignore # 忽略 .env、node_modules 等 ├── scripts/ │ ├── run_demo.js # 最小的自然语言用例 │ ├── run_recorder.js # 启动 recorder 的入口 ├── tests/ │ ├── login.test.js │ └── search.test.js ├── package.json └── README.md

借助 Recorder 录制功能配合自然语言维护脚本，整体效率比传统方式高一截。如果你准备在团队里推广这套方案，我建议先从两三个高频回归用例开始试点，让团队看到效果之后，再逐步扩大覆盖范围。

我的实际体验就到这里为止，接下来你可以先去把环境装了，跑通第一个自然语言用例，然后再回来读我后续要分享的实战篇和最佳实践篇。