#Web 环境配置

Midscene 可以在三种浏览器中操作网页：Midscene Chrome 插件、由 Playwright 或 Puppeteer 启动的浏览器，以及通过 Chrome Bridge 连接的桌面 Chrome。本文分别介绍它们的准备方式，只需准备你打算使用的那一种。

#Chrome 插件

插件在桌面版 Chrome 中运行 Playground，不需要工程或 Node.js。

1. 从 Chrome Web Store 安装 Midscene：

   

2. 在 Chrome 的扩展列表中打开 Midscene，浏览器右侧会出现 Midscene 侧边栏。

插件中保存的模型配置只存在于浏览器内，测试和脚本不会读取它，需要单独配置模型。

#Playwright

安装 Node.js ^20.19.0 || ^22.12.0 || >=24.0.0 和 pnpm。在项目目录中，如果还没有 package.json，先执行 pnpm init，然后安装依赖及 Chromium：

pnpm add -D @midscene/web playwright
pnpm exec playwright install chromium

Midscene Test 的 Web 项目已经依赖 Playwright，在该项目中只需执行 pnpm exec playwright install chromium。

#Puppeteer

pnpm add -D @midscene/web puppeteer

安装过程中需允许 Puppeteer 下载自带的浏览器。若使用本地已安装的浏览器或远程浏览器，请确保可执行文件路径或 CDP 调试地址可以访问。连接参数请参阅接入 Puppeteer。

#Chrome Bridge

如需复用桌面 Chrome 已有的标签页、登录状态或扩展程序，请先安装 Chrome 插件，再按照 Chrome Bridge 环境配置确认脚本可以通过插件控制 Chrome。

#验证

在 Playground 中验证 Chrome 插件。打开开始使用，页面已为你选好 Web 和 Playground，选择模型接入方式后，按步骤执行一次 aiAct 操作和一次 aiAssert 断言。断言通过即表示插件和模型调用都正常。

Playground 在插件中运行，不使用 Playwright 或 Puppeteer 的浏览器。如需验证这类浏览器，请在同一页面选择「创建 Midscene Test 项目」或「接入 JavaScript 测试工程」，按步骤第一次运行测试时就会用到这类浏览器。Chrome Bridge 请执行连接检查。

#常见问题

#是否可以手动安装 Chrome 插件？

如果无法访问 Chrome Web Store，可以从 GitHub Releases 页面 下载安装包并手动安装。但这种方式无法获得自动更新。

#运行失败，提示 Cannot access a chrome-extension:// URL of different extension

这通常由其他 Chrome 插件与 Midscene 冲突引起。例如，其他插件可能已经向页面注入 <iframe /> 或 <script />。

按照以下步骤查找发生冲突的插件：

1. 打开页面的开发者工具，找到 URL 以 chrome-extension:// 开头的 <iframe /> 或 <script />，并复制 URL 中的扩展 ID。
2. 打开 chrome://extensions/，根据扩展 ID 找到并禁用对应的插件。
3. 刷新页面并重试。

#在插件中使用 Ollama 模型时出现 403 错误

设置环境变量 OLLAMA_ORIGINS="*"，允许 Chrome 插件访问 Ollama 模型。

#测试或脚本无法打开页面

请确认已安装 Playwright 或 Puppeteer 的浏览器，并且运行测试的机器可以访问目标 URL。Playwright 或 Puppeteer 启动的浏览器使用全新的用户配置，无法使用桌面 Chrome 中的登录状态。如需复用登录状态，请使用 Chrome Bridge。