Codex × Playwright：浏览器操作自动化

难度：🟡 进阶级
耗时：⏱️ 10 分钟
适用环境：Codex / Claude Code / Antigravity

---

1. 场景价值与交付产物预览

传统的自动化脚本（如手写 Selenium/Puppeteer）需要开发者反复审查 DOM 树、写复杂的 CSS 选择器或 XPath，网页一旦小改版脚本就全挂。借助 Playwright MCP，Agent 可以直接读取网页视口截图与可访问性树（Accessibility Tree），自主判断输入框、按钮并模拟人类点击与滑动。

• 输入：目标网址与业务操作目标（如“访问目标网站并查询最新定价”）。
• 输出产物：目标页面完整高保真长截图、结构化提取的数据 JSON 以及可复现的自动化脚本。

---

2. 前置准备与环境配置

确保本地安装了 Chromium 运行时与 Playwright MCP 服务：

# 1. 全局安装或使用 npx 预热 Playwright
npx -y playwright install chromium

# 2. 验证 MCP 服务包
npx -y @modelcontextprotocol/server-playwright --version

---

3. 核心配置文件 (开箱即用)

在 MCP 配置文件中注入服务节点：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-playwright"],
      "env": {
        "HEADLESS": "true"
      }
    }
  }
}

---

4. 黄金 Prompt 指令流

请调用 Playwright MCP 执行以下端到端验证流程：

1. 启动浏览器并导航至：https://github.com/trending
2. 等待页面网络请求空闲（networkidle）；
3. 定位当前榜单中排名前 5 的开源项目，提取：
   - 项目名称（Repo Name）
   - Stars 增长数
   - 项目简短描述
4. 对整个榜单区域进行视口截图，保存为 `trending-top5.png`；
5. 将提取到的 5 个项目格式化为标准 JSON 输出至 `trending.json`。

---

5. 排障与避坑指南 (Troubleshooting)

1. 遇上 Cloudflare 5秒盾或验证码：
   • 解法：在 MCP 环境配置中设置 HEADLESS: false（开启有头浏览器），由人工完成一次性验证码，随后 Agent 继续接管。
2. 页面元素加载延迟导致报错：
   • 解法：Prompt 中明确要求在点击关键元素前必须添加 waitForSelector 显式等待。

---

6. 示例源码与产物资源

• 📁 自动化脚本产物：samples/playwright-crawler.ts
• 💡 遇到复杂 SPA 单页应用？查看进阶调优手册