Midscene.js 容器化部署实践：从零搭建视觉驱动的 UI 自动化服务
【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene
Midscene.js 是一个面向 E2E 测试的 GUI Agent，核心能力是用多模态大模型"看懂"截图，再执行点击、输入、断言等操作。它不依赖 DOM 或无障碍树，因此对纯图标按钮、canvas 画布、原生应用界面这类传统选择器够不到的目标同样有效。把 Midscene.js 放进容器里运行，适合两类场景：一是需要一个随时可用、环境固定的 Web 自动化执行节点；二是团队希望把"模型配置 + 脚本执行"封装成一条可复现的流水线，避免每个人本地装一套 Node 环境。
需要先说清楚一个事实：本仓库没有官方 Dockerfile 和 docker-compose 配置，下面的容器化方案是基于项目官方文档中可验证的依赖（Node 版本、@midscene/cli包、YAML 脚本运行器、模型环境变量）推导出的最小可行路径，供参考落地，不是官方镜像。
先想清楚：容器化能解决什么，解决不了什么
Midscene.js 的工作方式决定了它对外部环境的要求其实很少：一个 Node.js 运行时、一个能访问的多模态模型服务、一份 YAML 或 JS 脚本。这三样都适合放进容器。
但平台支持方面有明确的边界：
- Web 自动化：最契合容器场景。容器内跑
@midscene/cli驱动无头浏览器即可，无需与宿主机共享设备。 - Android / iOS 自动化：仓库中 packages/android/ 与 packages/ios/ 的实现依赖宿主机上的 adb、USB 调试或 WebDriverAgent 设备通道。设备在物理网络/USB 总线上，容器内无法直接摸到，这两类场景建议把 Midscene 跑在宿主机或具备设备接入能力的节点上，而不是塞进普通容器。
- 桌面端：需要访问真实的窗口与键鼠输入驱动，同理不适合纯容器。
所以本文的容器化方案只覆盖 Web 自动化这一条最干净的路径。如果你的目标是 Android 真机，直接看 apps/site/docs/zh/platforms/android 的设备准备文档更合适。
前提条件：先确认三件事
- Node.js 版本。仓库 package.json 的
engines字段声明支持20.19.0+、22.12.0+或24.0.0+。CLI 的执行路径使用 Rspack 工具链，遇到20.17.0这类旧补丁版本会直接报Unsupported Node.js version。选型时直接用 Node 22 LTS 或 24，绕开这个坑。 - 一个具备 UI 定位能力的多模态模型。Midscene 的元素定位完全基于截图，模型必须能看图。官方文档 支持的模型与配置 中列出了豆包 Seed、Qwen、GLM、Gemini、UI-TARS 等可选系列，任选其一并拿到 API Key 即可。
- 本地能跑通一次。在写 Dockerfile 之前，先用命令行在本地跑一遍完整流程，确认模型 Key 和脚本都正常，再把"跑通的环境"复制进容器。容器化放大的是稳定性，不是替你排错。
最小可用路径：本地跑通第一条自动化
按照 YAML 脚本运行器文档，最小闭环是三个文件：一个 YAML 脚本、一个.env、一条命令。
编写bing-search.yaml，描述"打开页面—执行操作—断言结果"三步：
page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 "今日天气" - sleep: 3000 - aiAssert: 结果显示天气信息在运行目录下创建.env，填入模型配置（注意 dotenv 约定，不写export前缀）：
MIDSCENE_MODEL_BASE_URL="你的模型服务地址" MIDSCENE_MODEL_API_KEY="你的 API Key" MIDSCENE_MODEL_NAME="模型名称" MIDSCENE_MODEL_FAMILY="模型系列"安装 CLI 并执行：
npm i -g @midscene/cli midscene ./bing-search.yaml预期结果：终端输出逐步执行进度，aiAssert全部通过后命令正常退出，同时生成一份可视化 HTML 报告。报告能回看每一步的截图和指令，是判断"到底跑通了没有"最直接的依据。
到这里你已经掌握了后续所有容器化配置需要覆盖的全部内容：Node 运行时、CLI、模型环境变量、脚本目录。
容器化配置：镜像、执行与验证
基于上面的最小闭环，镜像只需要做两件事：装好 Node 和 CLI，把工作目录留给脚本。
构建Dockerfile，只保留关键项：
FROM node:22-alpine RUN npm i -g @midscene/cli WORKDIR /work说明两个取舍：基础镜像选node:22-alpine是因为它落在engines声明的支持区间内，且体积小；用官方 npm 包@midscene/cli而不是源码构建，是因为源码是 pnpm monorepo（需要pnpm install+pnpm build走 nx 构建链），镜像复杂度和排错成本都高一个量级，除非你要改源码，否则没必要。
构建并执行：
docker build -t midscene-web . docker run --rm \ -v "$PWD/scripts:/work" \ -e MIDSCENE_MODEL_BASE_URL="你的模型服务地址" \ -e MIDSCENE_MODEL_API_KEY="你的 API Key" \ -e MIDSCENE_MODEL_NAME="模型名称" \ -e MIDSCENE_MODEL_FAMILY="模型系列" \ -w /work \ midscene-web midscene ./bing-search.yaml这里把脚本目录挂载到/work，模型配置通过-e注入而不是写死在镜像里——API Key 不应进镜像层，模型服务地址也随时可能换。
验证方式与本地一致：终端出现逐步进度、命令以 0 退出、生成可视化报告。如果容器执行成功而本地失败（或反过来），优先对比两边的 Node 版本（docker run midscene-web node -v）和实际生效的环境变量（可加--dotenv-debug参数调试 dotenv 加载逻辑）。
常见坑与排查顺序
脚本没生效、模型调用失败。.env必须放在工具运行目录下，与 YAML 文件所在目录无关；而且.env中的变量默认不覆盖已存在的全局环境变量。在容器里用-e注入后，若行为仍像"没配置"，先确认变量名拼写，再用--dotenv-debug看实际加载结果。
模型请求 403。如果你用的是本机 Ollama，Chrome 扩展访问 Ollama 时需要设置OLLAMA_ORIGINS="*"放行来源，这是官方快速开始文档里明确记录的解法。容器场景同理，把该变量一并注入即可。
Node 版本报错。Unsupported Node.js version只有一种解法：升级 Node 后重装依赖或全局 CLI。别在容器里用 node:18 镜像"先试试"，那是官方明确不支持的版本区间。
扩展冲突报错Cannot access a chrome-extension:// URL of different extension。这属于 Chrome Extension 场景的问题：其他扩展向页面注入了 iframe 或 script。按开发者工具里chrome-extension://开头的资源定位到扩展 ID，禁用后重试。容器内跑无头浏览器不受此影响，但如果你在宿主机调试扩展版本时遇到，排查路径是一样的。
脚本本身写错了。aiAssert失败不一定是环境问题，可能只是页面没加载完或断言描述与页面实际内容不符。用生成的报告回看失败步骤的截图，比反复看终端日志快得多。
进阶方向
跑通单条脚本之后，通常有三个自然的下一步：
- 接入 Playwright / Puppeteer 测试体系。仓库提供 集成到 Playwright 指南 与 集成到 Puppeteer 指南，把
aiAct、aiQuery、aiAssert三个核心 API 挂到你现有的浏览器测试用例上，Midscene 只负责"看和点"，页面导航和生命周期仍由你的框架管理。 - 升级到 Test Runner。新版 Test Runner 概览 提供了完整的测试生命周期、多环境并发隔离和标准化运行报告，是老版 YAML 运行器的官方替代方向，容器里批量执行脚本时收益更明显。
- 多模型分工。除了默认模型，还可以单独配置规划（planning）和洞察（insight）模型，例如用一个便宜快速的模型做断言、用强定位模型做操作，成本与稳定性的平衡点自己调。
容器化的价值到这里就收敛了：一个固定了 Node 版本和 CLI 版本的镜像，一份挂载进去的脚本目录，一组注入进去的模型环境变量。它没有创造新能力，只是把"这条命令在我机器上能跑"变成了"这条命令在任何节点上都能跑"。先把本地跑通，再谈容器，顺序反过来会浪费很多时间。
【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
