Playwright MCP 无头浏览器使用指南

让 Claude Code 拥有”眼睛和手”——通过 Playwright MCP 操控真实浏览器

一、它是什么

Playwright MCP 是微软开源的 MCP Server（github.com/microsoft/playwright-mcp），让 AI 编码助手能通过标准 MCP 协议操控真实浏览器。核心特点：

基于无障碍树（Accessibility Tree），不依赖截图/视觉模型，速度快、token 省
确定性操作，通过结构化数据定位元素，比截图点击更稳定
28+ 工具覆盖导航、点击、填表、截图、网络拦截、存储管理等

二、我的环境配置

# ~/.claude/.mcp.json
{
  "playwright": {
    "command": "playwright-mcp",
    "args": ["--headless", "--no-sandbox", "--caps", "vision,pdf"]
  }
}

参数	作用
`--headless`	无头模式，服务器/SSH 环境必须
`--no-sandbox`	Linux 非 root 用户需要
`--caps vision`	启用截图能力，Claude 能”看到”页面
`--caps pdf`	启用 PDF 保存能力

三、工具速查表

核心导航

工具	用途	关键参数
`browser_navigate`	打开 URL	`url`
`browser_navigate_back`	后退	无
`browser_snapshot`	获取页面无障碍快照（最常用）	`target`, `depth`
`browser_take_screenshot`	截图（需 vision cap）	`fullPage`, `filename`
`browser_close`	关闭浏览器	无

页面交互

工具	用途	关键参数
`browser_click`	点击元素	`target`（从 snapshot 获取的 ref）
`browser_type`	输入文本	`target`, `text`, `submit`
`browser_fill_form`	批量填表	`fields` 数组
`browser_select_option`	下拉选择	`target`, `values`
`browser_hover`	悬停	`target`
`browser_drag`	拖拽	`startTarget`, `endTarget`
`browser_press_key`	按键	`key`（如 `Enter`, `ArrowDown`）
`browser_file_upload`	上传文件	`paths`
`browser_handle_dialog`	处理弹窗	`accept`, `promptText`
`browser_wait_for`	等待文本出现/消失	`text`, `textGone`, `time`

高级功能

工具	用途	关键参数
`browser_evaluate`	执行 JS	`function`
`browser_run_code`	运行 Playwright 代码片段	`code`
`browser_console_messages`	获取控制台日志	`level`
`browser_network_requests`	查看网络请求	`filter`（正则）
`browser_tabs`	管理标签页	`action`（list/new/close/select）
`browser_resize`	调整窗口大小	`width`, `height`
`browser_pdf_save`	保存为 PDF（需 pdf cap）	`filename`

四、核心工作流：Snapshot 优先

最重要的最佳实践：优先使用 browser_snapshot 而非 browser_take_screenshot。

Snapshot 返回的是结构化的无障碍树，而非图片：

Token 消耗少（文本 vs 图片）
元素引用可以直接用于后续 browser_click 等操作
不需要视觉模型解析坐标

典型工作流：

1. browser_navigate → 打开页面
2. browser_snapshot → 获取页面结构，拿到元素引用（如 ref="e42"）
3. browser_click(target="e42") → 用引用精准点击
4. browser_snapshot → 确认操作结果

只在需要”看到”页面视觉效果时才用 browser_take_screenshot（比如检查 UI 样式、布局问题）。

五、实战场景

场景 1：检查自己开发的 Web UI

“帮我启动 dev server，打开页面看看渲染是否正常”

这是最常见的用法——开发 UI 后让 Claude 帮你验证。

你：帮我启动 Perfetto UI 的 dev server，然后打开 localhost:10000 看看页面是否正常加载

Claude 的操作：
1. Bash: npm run dev (启动 dev server)
2. browser_navigate: http://localhost:10000
3. browser_snapshot: 获取页面结构
4. browser_take_screenshot: 截图看视觉效果
5. 报告：页面加载正常，标题是 "Perfetto UI"，左侧导航栏有 X 个选项...

场景 2：自动化表单填写和测试

“帮我在 staging 环境创建一个测试工单”

你：打开 https://staging.example.com/issues/new，帮我填一个测试工单

Claude 的操作：
1. browser_navigate: https://staging.example.com/issues/new
2. browser_snapshot: 获取表单结构
3. browser_fill_form: 批量填写标题、描述、优先级
4. browser_click: 点击"提交"按钮
5. browser_snapshot: 确认提交成功

场景 3：抓取网页信息辅助开发

“帮我查一下这个 API 文档里 X 方法的参数”

你：打开 https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API，
    帮我查一下 fetch() 的 options 参数有哪些

Claude 的操作：
1. browser_navigate: 打开 MDN 页面
2. browser_snapshot: 获取页面结构化内容
3. 直接从无障碍树中提取信息，比 WebFetch 更准确

场景 4：调试前端网络请求

“页面加载慢，帮我看看网络请求”

你：打开 https://myapp.com，帮我检查哪些 API 请求比较慢

Claude 的操作：
1. browser_navigate: 打开页面
2. browser_network_requests: 列出所有网络请求
3. browser_network_requests(filter="/api/.*"): 过滤 API 请求
4. 分析：/api/dashboard 耗时 3.2s，可能是性能瓶颈

场景 5：保存网页为 PDF

“帮我把这个文档页面保存成 PDF”

你：把 https://playwright.dev/docs/api/class-page 保存为 PDF

Claude 的操作：
1. browser_navigate: 打开页面
2. browser_pdf_save(filename="playwright-page-api.pdf")
3. 文件已保存到输出目录

场景 6：Web 应用端到端验证流程

“帮我验证登录 → 创建 → 查看完整流程”

你：帮我走一遍完整的用户流程：登录 → 创建文章 → 确认文章出现在列表中

Claude 的操作：
1. browser_navigate: 打开登录页
2. browser_fill_form: 填写用户名密码
3. browser_click: 点击登录
4. browser_wait_for(text="Dashboard"): 等待登录成功
5. browser_click: 点击"新建文章"
6. browser_fill_form: 填写标题和内容
7. browser_click: 点击发布
8. browser_navigate: 打开文章列表
9. browser_snapshot: 确认新文章出现在列表中

场景 7：竞品分析/信息收集

“帮我看看竞品网站的定价页面”

你：打开 competitor.com/pricing，帮我整理出他们的定价方案

Claude 的操作：
1. browser_navigate: 打开定价页
2. browser_snapshot: 获取结构化内容
3. 整理成表格返回给你

场景 8：监控页面状态

“帮我检查生产环境 health check 页面是否正常”

你：帮我打开 https://prod.example.com/health 看看各项服务状态

Claude 的操作：
1. browser_navigate: 打开 health 页面
2. browser_snapshot: 获取状态信息
3. 报告：Database ✓, Cache ✓, Queue ✗ (连接超时)

六、进阶配置

持久化登录状态

如果你需要反复访问需要登录的网站，可以用持久化 profile：

{
  "playwright": {
    "command": "playwright-mcp",
    "args": ["--headless", "--no-sandbox", "--caps", "vision,pdf",
             "--user-data-dir", "/home/zbc/.cache/playwright-mcp-profile"]
  }
}

登录一次后，后续会话自动保持登录状态。Profile 位置默认在 ~/.cache/ms-playwright/mcp-chromium-{hash}。

隔离模式（测试推荐）

每次会话用全新环境，不保留任何状态：

{
  "playwright": {
    "command": "playwright-mcp",
    "args": ["--headless", "--no-sandbox", "--isolated"]
  }
}

模拟移动设备

{
  "playwright": {
    "command": "playwright-mcp",
    "args": ["--headless", "--no-sandbox", "--device", "iPhone 15"]
  }
}

使用代理

{
  "playwright": {
    "command": "playwright-mcp",
    "args": ["--headless", "--no-sandbox",
             "--proxy-server", "http://myproxy:3128"]
  }
}

忽略 HTTPS 错误（自签名证书）

{
  "playwright": {
    "command": "playwright-mcp",
    "args": ["--headless", "--no-sandbox", "--ignore-https-errors"]
  }
}

配置文件方式

复杂配置推荐用 JSON 配置文件：

// ~/.config/playwright-mcp.json
{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "headless": true
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  },
  "capabilities": ["core", "vision", "pdf"],
  "network": {
    "blockedOrigins": ["https://ads.example.com"]
  },
  "timeouts": {
    "navigation": 30000,
    "action": 10000
  }
}

然后引用：

{
  "playwright": {
    "command": "playwright-mcp",
    "args": ["--config", "/home/zbc/.config/playwright-mcp.json", "--no-sandbox"]
  }
}

七、最佳实践总结

DO（推荐做法）

Snapshot 优先：始终先用 browser_snapshot 获取页面结构，再做操作
用元素引用：从 snapshot 拿到的 ref 比 CSS 选择器更可靠
操作后验证：每次关键操作后 snapshot 确认结果
合理使用 wait_for：页面有动态加载时，先等待关键元素出现
使用 fill_form 批量填表：一次调用填多个字段，比逐个 type 高效
network_requests 调试：比 DevTools 更方便，可以让 AI 直接分析

DON’T（避免做法）

不要只靠截图操作：截图消耗大量 token 且无法从中提取元素引用
不要硬编码等待时间：用 browser_wait_for(text="xxx") 代替 wait_for(time=5)
不要忽略 snapshot 深度：大页面用 depth 参数限制，避免返回过大
不要在公共网络上关闭 sandbox：--no-sandbox 仅用于受信任环境
不要存密码在配置文件：敏感信息用 --secrets 加载 .env 文件

Snapshot vs Screenshot 选择

场景	用 Snapshot	用 Screenshot
获取页面内容/文本	O
点击按钮/链接	O
填写表单	O
检查 UI 视觉样式		O
验证布局/对齐		O
检查图片/图标是否正确		O
调试 CSS 问题		O

八、与 WebFetch 的对比

Claude Code 自带 WebFetch 工具也能获取网页内容，什么时候该用哪个？

场景	WebFetch	Playwright MCP
读取静态页面内容	O（更快）	O
需要 JS 渲染的 SPA	X	O
需要交互（点击/填表）	X	O
需要登录态	X	O
截图/PDF	X	O
网络请求分析	X	O
多步骤流程	X	O
快速获取 API 文档	O（够用）	O（更准确）

简单规则：静态内容用 WebFetch，需要交互/JS渲染/登录用 Playwright。

九、故障排查

浏览器启动失败

# 测试浏览器是否能运行
~/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  --headless --no-sandbox --dump-dom about:blank

缺少系统依赖

# 需要 sudo 权限
sudo npx playwright install-deps chromium

MCP Server 连接测试

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
  | timeout 10 playwright-mcp --headless --no-sandbox 2>/dev/null

应返回包含 "serverInfo":{"name":"Playwright"} 的 JSON。

页面加载超时

增加导航超时：--timeout-navigation 120000（2分钟）

VAAPI 警告

ERROR:media/gpu/vaapi/vaapi_wrapper.cc: Installed VAAPI version is too old

这是显卡驱动相关的警告，不影响无头模式功能，可以忽略。

十、参考资源

资源	说明
microsoft/playwright-mcp	官方仓库，最权威的文档来源
Playwright 官方文档	Playwright 核心文档
MCP 协议规范	MCP 协议标准
npm @playwright/mcp	npm 包页面，版本更新日志
Playwright MCP Docker	Docker 镜像，适合 CI/CD

最后更新：2026-04-22 环境：@playwright/mcp@0.0.70, Chromium 147, Ubuntu 22.04, Claude Code

Quartz 4

Explorer

Playwright_MCP_无头浏览器使用指南