CodeBuddy中配置Playwright MCP 浏览器自动化完全指南-尧图网络科技

CodeBuddy中配置Playwright MCP 浏览器自动化完全指南

适用环境：Windows + CodeBuddy，配置文件C:\Users\admin\.codebuddy\mcp.json（写入mcpServers节点）。本文基于已实测跑通的版本（@playwright/mcp@latest，默认内核 chrome-for-testing）。

一、Playwright MCP 是什么

Playwright MCP是微软官方出品的 MCP Server，让 AI 通过真实浏览器自动完成网页操作：打开页面、点击、输入、截图、跑 E2E 验证、抽取页面数据。

它的核心特点是基于"可访问性快照（accessibility snapshot）"交互，而非靠截图/坐标定位：

页面结构被抽象成带ref的元素树
AI 用ref精准定位按钮/输入框（如ref=e46），页面重排也不会点错
比"截图 + 坐标"更稳、token 更省

本地还是公网都能访问——它跑的是真实浏览器，browser_navigate填什么 URL 就开什么（localhost 或https://www.bing.com无区别）。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、安装与配置

2.1 写入 MCP 配置

"playwright":{"command":"D:/SoftWare/node22/npx.cmd","args":["-y","@playwright/mcp@latest","--browser","chromium"],"description":"浏览器自动化（Playwright，可访问性快照）","disabled":false}

常用args参数：

参数	说明
`--browser chromium`	指定内核（chromium / firefox / webkit），默认 chromium
`--headless`	无头模式（默认即无头；想看界面去掉此参数）
`--no-sandbox`	Linux/容器常用；Windows 一般不用
`--cdp-endpoint <url>`	连已打开的浏览器（如`http://127.0.0.1:9222`），可复用登录态
`--port <n>`/`--host`	以 HTTP 服务形式暴露（远程 MCP）
`--save-trace`	保存 trace 便于调试

写完配置必须重启 MCP 连接（禁用→启用，或重启 CodeBuddy），否则仍跑旧进程。

2.2 安装浏览器内核（关键一步，否则报错）

首次运行会报：

Error: Browser "chrome-for-testing" is not installed. Run `npx @playwright/mcp install-browser chrome-for-testing` to install

解决（在 PowerShell 执行）：

D:/SoftWare/node22/npx.cmd-y @playwright/mcp@latestinstall-browserchrome-for-testing

会下载约 191.9 MiB 内核到C:\Users\admin\AppData\Local\ms-playwright\，装好即可复用。

2.3 国内网络注意事项

用国内镜像PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright时，可能遇到特定版本 404（实测chrome-for-testing 151.0.7922.10在 npmmirror 缺失）。
实测去掉镜像、走官方源（https://cdn.playwright.dev）可正常下载（约几分钟，191.9 MiB）。
结论：镜像 404 就回退官方源。

三、常用工具速查

工具	作用
`browser_navigate`	打开 URL（`{"url": "..."}`）
`browser_snapshot`	抓取可访问性快照（拿元素`ref`，比截图更适合定位）
`browser_type`	向可编辑元素输入文本；`submit:true`等效"输入后回车"
`browser_click`	点击（靠快照`ref`或 selector 定位）
`browser_press_key`	按键（如`Enter`、`ArrowLeft`）
`browser_take_screenshot`	截图（视觉验证时再用，不能据此做操作）
`browser_evaluate`	在页面执行 JS，取回结构化结果
`browser_wait_for`	等待某条件/元素出现
`browser_navigate_back`	后退

注意：本版本没有browser_fill，输入框用browser_type（填完可submit:true自动回车）。

四、常用开发场景示例

场景 1：本地前端冒烟测试

打开http://localhost:5173，截图首页，点"登录"看是否跳转。

调用链：navigate→take_screenshot→snapshot（拿 ref）→click→wait_for→take_screenshot+snapshot断言。

场景 2：表单 E2E 流程

打开 login 页，用户名填admin、密码填123456，点提交，验证"登录成功"。

snapshot拿 input/button 的 ref → 两次type→click→snapshot断言。

场景 3：抓取页面数据

打开列表页，用browser_evaluate把表格前 20 行"名称+状态"取成结构化数据。

场景 4：控制台 / 网络错误排查

操作到报错那步，看 console 红字 / 网络 500。

用browser_evaluate注入监听console.error/ 失败网络，或直接读browser_console_messages/browser_network_requests（若提供）。

场景 5：响应式 / 多视口检查

首页分别在 375 / 768 / 1440 宽度截图，查布局错位。

场景 6：自动化回归（穷人版视觉回归）

改完登录页样式，重跑流程截图，和基线图对比。

可配合--save-trace导出 trace 回放。

场景 7：连已登录浏览器，跳过登录

配--cdp-endpoint http://127.0.0.1:9222（先chrome --remote-debugging-port=9222手动登录），AI 复用登录态操作受限页面。

场景 8：公网页面（与本地无异）

打开https://www.bing.com，截图、搜索、抽取结果。

五、完整实战：用 Bing 搜索并提取前 5 条标题

目标：打开https://www.bing.com→ 截图首页 → 搜"Spring AI Alibaba" → 取前 5 条标题。

实际调用链（已跑通）：

// 1. 打开首页browser_navigate({url:"https://www.bing.com"})// → 自动跳转 https://cn.bing.com/// 2. 首页截图browser_take_screenshot({type:"png",scale:"css",filename:"bing-home.png"})// 3. 快照定位搜索框（ref=e46）browser_snapshot()// → searchbox "输入搜索词" [ref=e46]// 4. 输入并回车搜索browser_type({target:"e46",text:"Spring AI Alibaba",submit:true})// → 跳转 https://cn.bing.com/search?q=Spring+AI+Alibaba// 5. 抽取前 5 条标题browser_evaluate({function:"() => { const nodes = Array.from(document.querySelectorAll('li.b_algo h2')).slice(0,5); return nodes.map(n => (n.innerText||n.textContent||'').trim()).filter(Boolean); }"})// 6. 结果页截图browser_take_screenshot({type:"png",scale:"css",filename:"bing-result.png"})

结果（前 5 条）：

#	标题
1	Spring AI Alibaba 概述 - Alibaba Cloud Spring Cloud …
2	Spring AI Alibaba实战：从0到1构建企业级智能应用
3	GitHub - alibaba/spring-ai-alibaba: Agentic AI Framework for …
4	Spring AI Alibaba
5	快速开始 \| Spring AI Alibaba

截图文件：bing-home.png、bing-result.png（真实浏览器渲染的 PNG）。

六、常见问题与排错

现象	原因 / 解决
`Browser "chrome-for-testing" is not installed`	首次需`npx @playwright/mcp install-browser chrome-for-testing`装内核。
下载报 404（`npmmirror`路径）	镜像缺该版本，去掉`PLAYWRIGHT_DOWNLOAD_HOST`走官方源即可。
`browser_fill`工具不存在	本版本用`browser_type`（`submit:true`自动回车），不要调`browser_fill`。
改配置不生效 / 仍跑旧进程	禁用→启用或重启 CodeBuddy。
`npx`拉包慢 / 缓存损坏 ENOENT	清`C:\Users\admin\AppData\Local\npm-cache\_npx`重试。
公网站登录需验证码	用`--cdp-endpoint`连已手动登录的真实 Chrome 绕过。
反爬 / 人机验证挡住	Cloudflare、reCAPTCHA 等自动化浏览器过不去，属正常限制。
headless 被站点识别为机器人	去掉`--headless`或连`--cdp-endpoint`真实 Chrome。
截图中文乱码	Windows 本地一般正常；容器/无字体环境需装中文字体。
控制台有 error	多为页面自身资源告警，不影响自动化；可忽略或`browser_evaluate`排查。

七、与 Puppeteer 对比 / 选型

维度	Puppeteer	Playwright（推荐）
交互方式	截图 + 选择器/坐标	可访问性快照（ref 定位）
稳定性	受布局/坐标影响	高（语义定位）
Token 消耗	截图多，偏贵	快照文本，更省
多浏览器	Chromium 为主	chromium/firefox/webkit
E2E 推荐度	中	高
截图需求	强	强

结论：做 E2E 验证、表单交互、数据抽取，优先Playwright；纯截图存档或习惯 Puppeteer 脚本时用后者。

一句话总结：Playwright MCP = 真实浏览器 + 快照定位 + 全公网/本地通吃。配好内核、记牢"先navigate/snapshot拿 ref，再type/click，最后evaluate抽数据 /screenshot留图"这套流水线，就能覆盖绝大多数浏览器自动化场景。