3 min read562 words

Playwright MCP 基础操作

Playwright MCP 是浏览器自动化类工具中功能最完整的选择。本节从安装配置开始，通过实际操作场景覆盖核心工具的使用方式。

安装与初始化

# 安装 Playwright MCP
npm install -g @playwright/mcp
# 安装浏览器（首次运行必须）
npx playwright install chromium
# 可选：安装所有浏览器
npx playwright install

配置（Claude Desktop）

{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp",
"--browser", "chromium",
"--headless",
"--viewport", "1280x720"
]
}
}
}

参数说明：

参数	说明	推荐值
`--browser`	浏览器引擎	`chromium`（最兼容）
`--headless`	无头模式，不显示窗口	生产用 `--headless`，调试去掉
`--viewport`	视口尺寸	`1280x720`（标准桌面）
`--user-data-dir`	用户数据目录，保存 Cookie/登录态	需要登录时指定
`--ignore-https-errors`	忽略 HTTPS 错误	仅用于开发环境

核心工具速查

Playwright MCP 暴露的主要工具及典型用法：

导航与页面操作

工具：browser_navigate
用途：导航到 URL
示例：browser_navigate(url="https://news.ycombinator.com")

工具：browser_go_back / browser_go_forward
用途：浏览器历史导航
示例：browser_go_back()

工具：browser_wait_for_text
用途：等待页面出现特定文本（处理异步加载）
示例：browser_wait_for_text(text="登录成功", timeout=5000)

元素交互

工具：browser_click
用途：点击页面元素
示例：browser_click(element="Submit button", ref="...")

工具：browser_type
用途：在输入框输入文本
示例：browser_type(element="Search input", text="MCP tutorial")

工具：browser_select_option
用途：选择下拉框选项
示例：browser_select_option(element="Country dropdown", values=["CN"])

内容提取

工具：browser_take_screenshot
用途：截取当前页面截图
示例：browser_take_screenshot()

工具：browser_snapshot
用途：获取页面的可访问性树（结构化文本，比截图更适合信息提取）
示例：browser_snapshot()

工具：browser_get_text
用途：获取页面或元素的文本内容
示例：browser_get_text(element="article")

实战：抓取 Hacker News 热门帖

sequenceDiagram participant U as 用户 participant C as Claude participant P as Playwright MCP U->>C: "抓取今天 HN 前10条帖子的标题、分数和链接" C->>P: browser_navigate(url="https://news.ycombinator.com") P-->>C: 页面加载完成 C->>P: browser_snapshot() P-->>C: 页面结构（包含所有帖子信息） C-->>U: 整理后的TOP10列表

提示词：

请：
1. 打开 https://news.ycombinator.com
2. 获取页面快照
3. 提取前10条帖子的：标题、分数、评论数、链接
4. 以 Markdown 表格格式输出

使用 browser_snapshot() 而不是截图，原因是快照返回文本结构，Claude 可以直接解析，不需要视觉理解截图。

实战：填写表单并提交

提示：
1. 打开 https://myapp.com/feedback
2. 在"姓名"输入框填入"测试用户"
3. 在"评论"区域填入"这是自动化测试内容"
4. 点击"提交"按钮
5. 截图确认提交结果

Claude 会自动：

browser_navigate(url="https://myapp.com/feedback")
browser_snapshot() — 找到输入框和按钮的引用
browser_type(element="姓名 input", text="测试用户")
browser_type(element="评论 textarea", text="这是自动化测试内容")
browser_click(element="提交 button")
browser_take_screenshot()

处理动态页面（SPA）

对于 React/Vue 等单页应用，需要等待内容渲染完成：

提示：
1. 打开 [SPA网址]
2. 等待3秒让页面加载完成（或等待特定文本出现）
3. 然后再提取内容

Claude 会调用：

browser_navigate(url="...")
browser_wait_for_text(text="数据加载完成", timeout=5000)
browser_snapshot()

如果没有明确的加载完成标志，可以用 browser_evaluate 注入等待：

// 等待页面无网络请求活动
await page.waitForLoadState('networkidle')

保存登录态

需要访问需要登录的页面时，使用 --user-data-dir 保存会话：

{
"mcpServers": {
"playwright-logged-in": {
"command": "npx",
"args": [
"@playwright/mcp",
"--browser", "chromium",
"--user-data-dir", "/Users/yourname/.playwright-profile"
]
}
}
}

第一次运行时去掉 --headless，手动登录。浏览器会把 Cookie 保存到 profile 目录，之后的会话自动复用。

常见问题

问题	原因	解决方案
点击无反应	元素被遮挡或未完全加载	加 `browser_wait_for_text` 等待
截图全是空白	headless 下 SPA 未渲染	增加等待时间或用 networkidle
提示找不到元素	选择器与快照不匹配	先 snapshot 看页面结构再操作
Cookie 丢失	未设置 user-data-dir	配置持久化 profile 目录

本节执行清单

[ ] 安装 Playwright MCP 并运行 npx playwright install chromium
[ ] 测试基本的 navigate + snapshot + click 流程
[ ] 理解 browser_snapshot 比截图更适合信息提取的原因
[ ] 需要登录的场景：配置 --user-data-dir 保持登录态

下一节：信息提取与结构化输出