Playwright MCP 使用教程：让 AI 助手完成网页查询和筛选

如果任务需要按网页当前状态筛选内容、打开详情再整理结果，MCP 浏览器工具可以让助手逐步完成。关键是让每一步基于当前页面证据，而不是让助手猜一个元素编号连续点击。

本文用图书练习站完成“进入 Travel 分类 → 选择三本书 → 查看详情 → 整理来源与价格 → 保存截图”。重点是一个可检查的操作流程，不讨论模型之间的横评，也不需要视觉模型来解释每次点击。

准备输入地址

先在浏览器找到下列页面并确认内容，再从地址栏复制完整地址。服务或仓库地址从相应账户设置、官方项目的接入说明或克隆菜单取得。不要从示例输出中反推真实地址。

BOOKS_LIST_URL：Books to Scrape 首页地址。

下文 JSON 或任务参数中的 <变量名> 是待替换标记，提交前填写刚复制的实际值；JSON 不会自动展开环境变量。结果示例中的 example.16yun.cn 只表示来源字段的形状，不是本文部署的演示站。

准备客户端与浏览器

需要 Node.js 24、已经安装的 Chrome，以及支持 MCP 的客户端。先确认：

node --version
npx -y @playwright/mcp@latest --help

客户端 MCP 设置加入：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y", "@playwright/mcp@latest",
        "--browser", "chrome",
        "--headless",
        "--isolated"
      ]
    }
  }
}

这份配置使用动态发布版本。接入后记录实际包版本；团队固定版本时，把 latest 换成已经确认的版本号。参数、工具 Schema 与文件路径规则见 Playwright MCP 官方说明。

隔离模式不保存本轮 Cookie 与本地状态，适合公开练习站。需要复用登录态时，应采用明确的独立用户目录或存储状态，不能期待关闭隔离会话后登录仍保留。

第一步：打开页面，检查快照

连接成功后确认工具列表包含导航、快照、点击、截图与关闭能力。调用 browser_navigate：

{"url": "<BOOKS_LIST_URL>"}

再用 browser_snapshot 读取当前可访问性结构。你应看到分类导航和商品列表。在快照里找到名为 Travel 的链接，而不是根据页面截图估计它在第几行。

快照中的引用来自当前页面状态，不是永久元素 ID。页面跳转、列表替换或弹窗出现后都需要重新检查。本文不预先给出 e5、e12 这类固定值，因为你的会话中它们可能指向别的元素。

第二步：选择分类并确认筛选已经生效

在客户端工具参数里，把当前 Travel 引用填入 browser_click 的 target。当前官方工具也允许唯一选择器，但引用必须来自刚取得的快照：

{
  "target": "<替换为当前快照中的 Travel 引用>",
  "element": "Travel 分类链接"
}

角括号内容是待替换说明，不能原样提交。某些旧版本使用 ref 字段；以你连接的工具 Schema 为准，不混用两个版本的参数。

点击后重新取快照，确认标题已经是 Travel，商品列表与分类相符。不要只看工具返回“已点击”，就继续采集原来总目录的前三本书。

第三步：逐本查看详情，而不是只读截断标题

从筛选后的当前列表选择三本不同的书。对每本书：

从最新快照取得标题链接引用并打开。
检查详情页标题和地址，读取商品信息表中的 UPC 与含税价格。
保存这条记录的完整标题、币种和当前详情 URL。
返回分类页后重新取快照，再打开下一本。

这里不把书名作为去重键。若两次进入同一 UPC，应该回到分类列表选另一项，而不是为了得到三行结果重复保留。

可以给助手如下完整任务说明：

在 Books to Scrape 中进入 Travel 分类。
只选择该分类中的三本不同图书，逐本进入详情页。
保存完整书名、UPC、Price (incl. tax)、币种和实际详情 URL。
每次页面变化后重新读取快照。遇到访问失败单独记录，不猜缺失字段。
完成后返回三条记录，并说明是否存在失败或重复 UPC。
不要执行购买、登录或任何写入站点数据的操作。

这是任务意图，不保证助手无需检查就会自动正确完成。观察实际工具调用，核对分类与详情来源，才是判断结果的方法。

第四步：保存结果与截图

整理结果时，输出 JSON 字段应固定；下面只表示结构：

{
  "category": "Travel",
  "records": [
    {
      "upc": "从详情读取",
      "title": "详情完整标题",
      "price_including_tax": "页面十进制金额",
      "currency": "GBP",
      "source_url": "实际详情地址"
    }
  ],
  "failures": []
}

练习站的价格是演示数据。不能根据上述结构声明已经取得三本真实报价，也不要把缺少记录的数组包装成完整任务。

返回分类页后，用 browser_take_screenshot 保存可核对的页面状态：

{"type": "png", "filename": "travel-list.png", "fullPage": true}

显式相对文件名按 MCP 客户端工作区根目录解析，不应假设它一定在你手动打开的终端目录。工具返回路径后检查对应位置。未显式命名时，输出目录参数才决定自动命名文件的去向。

截图帮助回看筛选状态，不替代字段数据。采集整页时使用 fullPage；元素截图与整页截图不是同一种请求。

完成前怎样检查

确认 category 是 Travel，记录来自该分类，三条 UPC 不重复，每条 source_url 能回到对应详情，价格含义一致。如果只有两条合格数据，保留失败说明，不让助手从记忆里补第三条。

最后调用 browser_close 结束本轮浏览器。隔离会话关闭后状态丢失是预期行为，不是登录保存故障；长期复用会话需要另一套明确配置。

常见问题与修复

客户端启动不了 npx。 检查桌面进程 PATH 与 Node 安装。先让同一环境可以读取 help，再检查客户端配置，不直接修改页面操作步骤。

提示浏览器不可用。 确认 --browser 选择的 Chrome 已安装，并按服务返回信息检查可执行路径。不要因为缺浏览器而无条件添加禁用沙箱等无关参数。

点击引用失效。 页面已经变化，重新取 snapshot 并选择新的引用。不要在旧编号上反复重试。

页面上有链接，快照找不到。 检查是否在折叠菜单、iframe、弹窗或未加载区域，必要时结合截图理解当前状态，再使用对应的浏览器工具操作。

工具参数提示没有 ref。 当前 Schema 可能使用 target；检查实际工具参数并同步调用，不照抄旧版本例子。

截图找不到。 查看工具返回的文件路径及工作区根目录。不要只在默认下载文件夹中寻找。

操作都成功，但结果分类不对。 在筛选动作后增加标题和来源检查；“点击完成”不是业务筛选已生效的证据。

这套流程的重点是每次动作后取得新的页面依据。助手负责组合工具，任务范围和最终结果仍应由来源与字段核对来约束。