常见问题

安装

Ignored build scripts: esbuild / sharp pnpm 10+ 默认拦截构建脚本。仓库 pnpm-workspace.yaml 的 allowBuilds 已放行，确认 pnpm 版本后重新 pnpm install。不要把配置写到 package.json 的 pnpm 字段，pnpm 10 以后不读那里。

Chromium 下载慢或失败 设置镜像后重装：

PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright pnpm exec playwright install chromium

运行

unknown node 报错 直接 midscene-test cases/xxx.yaml 不会加载 midscene.config.ts。一定用 pnpm test、pnpm test:web、pnpm test:android，它们带了 --config。

模型报 401 / 403.env 里 Key 没填或填错，或者 Key 没开通对应模型。pnpm verify 能单独验。

模型报 429 或超时 并发太高或额度用完。先单个用例跑；长期解决找负责人加额度。

AI 步骤每次都找不到元素 看报告截图。常见原因：页面没加载完（加 aiWaitFor）、描述有歧义（加位置词）、目标在屏幕外（先 aiScroll）。

第一个失败后就停了midscene.config.ts 里 test.bail: 1 的设计。想跑完看全貌，临时把 bail 改大或删掉。

浏览器一闪而过看不清.env 里 HEADLESS=false。

Android

adb devices 显示 unauthorized 手机上重新点允许 USB 调试，勾选"始终允许"。

adb devices 为空 换线、换口；Windows 装厂商驱动；三星手机确认 USB 模式不是"仅充电"。

用例中途手机锁屏 开发者选项里打开"充电时屏幕不休眠"。

多台设备报错.env 里 ANDROID_DEVICE_ID 指定一台。

报告

报告在哪midscene_run/report/，按时间戳命名的 HTML。

报告太大 每步都截图，长用例几十 MB 正常。提单附件传不动就压缩或只截关键步骤。

还是不行

带上完整终端输出和报告，在群里 @ 框架负责人。