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 配置

json 复制代码

"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 执行）：

powershell 复制代码

D:/SoftWare/node22/npx.cmd -y @playwright/mcp@latest install-browser chrome-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 条标题。

实际调用链（已跑通）：

js 复制代码

// 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 留图"这套流水线，就能覆盖绝大多数浏览器自动化场景。