Playwright CLI 工作流实战指南：从标准交互循环到会话隔离与故障排查

本文是 Playwright CLI Skill（位于本仓库 skills/.curated/playwright）配套工作流文档的系统化解读，面向需要在终端中驱动真实浏览器完成页面自动化、表单提交、数据提取与 UI 调试的开发者与 AI Agent。读完本文，你将掌握 pwcli 的标准交互循环、元素引用（element ref）的使用时机、会话隔离机制、配置文件语法，以及一套可复现的故障排查流程，并理解底层 wrapper 脚本的工作原理。

前置约定与运行环境

文档中的工作流命令统一基于两个约定：

• PWCLI 环境变量指向 wrapper 脚本的绝对路径；
• pwcli 是 "$PWCLI" 的便捷别名。

在本仓库中运行命令时，建议先进入 output/playwright/<label>/ 目录再执行，以便把截图、PDF、trace 等产物集中收纳在固定位置，避免在仓库顶层引入零散文件。

wrapper 脚本位于 scripts/playwright_cli.sh，按如下方式配置一次即可：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
alias pwcli="$PWCLI"

由于 wrapper 依赖 npx（详见后文实现分析），使用前应先确认环境：

command -v npx >/dev/null 2>&1

若 npx 缺失，需要先安装 Node.js/npm，然后可以全局安装 CLI 作为可选替代方案：npm install -g @playwright/cli@latest。完整的命令清单可参考同目录下的 references/cli.md。

标准交互循环：快照驱动的核心节奏

Playwright CLI 工作流的核心原则只有一条：频繁使用 wrapper 脚本并经常快照（snapshot）。快照会返回当前页面的可交互元素及其稳定引用（形如 e3、e12 的 ref），后续所有操作命令都依赖这些 ref。一旦导航或页面发生显著变化，旧 ref 就会失效，此时必须重新快照。

最基本的交互循环如下：

pwcli open https://example.com
pwcli snapshot
pwcli click e3
pwcli snapshot

可以看到，每次可能改变 DOM 的操作之后都要紧跟一次 snapshot。按照 SKILL 文档 SKILL.md 的指引，在以下时机应重新快照：

• 页面导航之后；
• 点击了会显著改变 UI 的元素之后；
• 打开/关闭模态框（modal）或菜单之后；
• 切换标签页之后。

从源码结构看，这种“快照 → 取 ref → 操作 → 再快照”的循环保证了 Agent 或脚本始终基于最新 DOM 状态进行决策，是避免引用过期导致命令失败的根本手段。

表单提交：填写、点击、验证、留证

处理登录、注册、搜索等表单场景时，推荐显式使用 --headed 打开浏览器以便观察过程，然后依次填写、提交并快照确认，最后截图留证：

pwcli open https://example.com/form --headed
pwcli snapshot
pwcli fill e1 "[e-mail]"
pwcli fill e2 "password123"
pwcli click e3
pwcli snapshot
pwcli screenshot

fill 负责向输入框填充文本，click 触发提交，snapshot 校验提交后的页面状态（成功提示或错误信息），screenshot 生成可视化证据。对于需要模拟按键场景的，pwcli 还支持 type "search terms"、press Enter 等键盘类命令（见 references/cli.md）。SKILL 文档特别强调：在引用 e12 这类元素 id 之前，必须确保已执行过快照。

数据提取：用 eval 读取页面内容

无需逐字段点击复制时，可以直接用 eval 在页面上下文执行表达式来提取数据。eval 有两种形态：

pwcli open https://example.com
pwcli snapshot
pwcli eval "document.title"
pwcli eval "el => el.textContent" e12

• 第一种传入一段普通表达式（如 "document.title"），返回该表达式的求值结果；
• 第二种传入一个箭头函数（如 "el => el.textContent"），并附上元素 ref（如 e12），函数会以该元素为参数被调用，从而拿到元素级文本或属性。

这种模式适合抓取标题、列表项文本、表格单元格等结构化数据。需要注意的是，SKILL 文档的 Guardrails 建议优先使用显式命令（fill、click 等）而非 eval/run-code，仅在确实需要时才使用求值类命令。

调试与检查：复现问题并采集现场

当页面行为异常时，可以在复现问题的同时采集两类关键现场信息——控制台消息与网络活动：

pwcli console warning
pwcli network

console 命令默认抓取全部控制台输出，也可以像上面这样只过滤 warning 级别（同样支持 error 等其他级别，详见 references/cli.md）；network 输出网络请求记录，可用于排查资源加载失败、接口返回异常等问题。

对怀疑存在时序问题或交互异常的流程，建议录制 trace（Playwright 的跟踪记录），完整覆盖问题复现过程：

pwcli tracing-start
# 在这里手动复现问题
pwcli tracing-stop
pwcli screenshot

tracing-start 开启录制，复现完问题后 tracing-stop 收尾，再配合 screenshot 留存视觉证据。trace 文件可在后续离线回放，便于定位是哪一步交互触发了异常。

会话隔离：用 Sessions 分离多项目工作

当多个任务共用同一个浏览器时，Cookie、localStorage 等状态会相互污染。pwcli 通过命名会话（session）实现状态隔离：不同名称的 session 各自拥有独立的浏览器上下文。

按命令粒度指定会话：

pwcli --session marketing open https://example.com
pwcli --session marketing snapshot
pwcli --session checkout open https://example.com/checkout

上面的示例中，marketing 与 checkout 两个会话互不干扰。如果后续命令都在同一个会话中执行，也可以用环境变量一次性指定，避免每条命令重复带 --session：

export PLAYWRIGHT_CLI_SESSION=checkout
pwcli open https://example.com/checkout

关于环境变量与会话的优先级，可以从 wrapper 脚本的实现中得到确认：脚本会先扫描参数中是否包含 --session 标志；只有当命令行参数没有指定会话、且环境变量 PLAYWRIGHT_CLI_SESSION 非空时，才会自动注入该会话名（见下文实现分析）。这一设计使得“显式参数优先于环境变量”成为可预期行为。

配置文件：定制浏览器启动参数

默认情况下，CLI 会读取当前目录下的 playwright-cli.json 作为配置文件；若文件不在当前目录，可通过 --config 参数指定具体路径。

最小可用配置示例：

{
  "browser": {
    "launchOptions": {
      "headless": false
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  }
}

配置分两层：

• launchOptions：浏览器启动参数。headless: false 表示以有头（可见）模式启动，适合需要人工观察或与 --headed 配合的调试场景；不设置时默认走无头模式。
• contextOptions：浏览器上下文参数。viewport 用于固定视口尺寸（示例为 1280×720），保证每次运行时页面布局一致，截图的宽高比也因此稳定可复现。

其他常用的 launchOptions 可按需扩充（如 args、executablePath 等），但以上最小配置已足以覆盖绝大多数“固定视口 + 有头调试”的需求。

故障排查：三类高频问题的标准解法

工作流文档给出了三条非常实用的排错经验：

1. 元素 ref 失效：如果某条命令因 ref 找不到元素而失败，先重新执行 pwcli snapshot 拿到最新 ref，再重试原命令。快照是获取 ref 的唯一合法入口，SKILL 文档的 Guardrails 也明确禁止用 run-code 绕过 ref 体系。
2. 页面渲染不符合预期：用 --headed 重新打开页面，并配合 resize 1920 1080 调整窗口尺寸后重试。很多“看起来不对”的问题其实是视口过小或元素被遮挡所致。
3. 流程依赖先前状态：如果某条流程依赖前序操作留下的状态（如登录态、已选中的选项），请使用命名 --session 保持上下文连续性，避免状态丢失或串扰。

这套排查思路与“先快照、再操作、必要时有头复现”的总体原则一致，能够覆盖绝大多数日常自动化失败场景。

底层实现：wrapper 脚本如何让 CLI 免安装即用

要理解上述工作流为何能以 pwcli 一条命令驱动，关键在于查看 scripts/playwright_cli.sh 的实现。脚本核心逻辑如下：

• 启动时校验 npx 是否存在于 PATH，缺失则直接报错退出——这正是 SKILL 文档要求先检查 npx 的原因；
• 遍历全部参数，探测是否已经包含 --session 或 --session=*；
• 以 npx --yes --package @playwright/cli playwright-cli 构造执行命令，其中 --yes 自动确认安装、--package 指定临时加载的 CLI 包，从而做到无需全局安装即可运行；
• 仅当参数中未指定会话且环境变量 PLAYWRIGHT_CLI_SESSION 非空时，向命令头部注入 --session <值>；
• 最后通过 exec 将拼接好的完整命令交给当前 shell 进程执行。

从这段实现可以推断：wrapper 的职责本质上是“npx 按需拉包 + 会话参数自动注入”，所有浏览器行为仍由 @playwright/cli 本身完成。该 skill 的 NOTICE.txt 也说明，其内容改编自 Microsoft 的 playwright-cli，并针对 Codex skill 集合做了包装脚本与本地参考文档的适配。

总结

本文从 references/workflows.md 出发，系统梳理了 Playwright CLI 的六大实战场景：快照驱动的标准交互循环、表单提交流程、eval 数据提取、控制台/网络/trace 三重调试手段、命名会话隔离，以及 playwright-cli.json 配置定制，并给出了三类高频故障的标准解法。配合 references/cli.md 的完整命令参考与 SKILL.md 的使用守则，读者可以在终端中稳定地完成从“打开页面”到“产出截图与 trace 证据”的完整浏览器自动化闭环。