Midscene.js 容器化部署实践从零搭建视觉驱动的 UI 自动化服务【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.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 installpnpm 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。如果你用的是本机 OllamaChrome 扩展访问 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），仅供参考