Clawbrowser – 通过 Playwright CLI 控制浏览器

[](https://clawaudit.duckdns.org/audit/f4d4fb45-ed25-4659-8235-2459d0dc8189)

[](https://clawaudit.duckdns.org/audit/a55cb413-b111-4f1a-9f39-a5c857090ebf)

安装与使用指引

1. 安装 CLI 工具并验证可用性：

npm install -g @playwright/cli@latest
playwright-cli --help

CLI 默认以无头模式运行；若需查看界面，请在 open 命令中添加 --headed，或在 playwright-cli.json 中设置 browser.launchOptions.headless 为 false。

1. CLI 默认读取 playwright-cli.json 配置文件，也可通过 --config 指定其他文件。使用配置文件可统一设置浏览器名称、启动/上下文选项、视口大小、超时时间、输出目录及录制参数，无需每次修改命令。

1. 保持 playwright-cli --help 在终端中随时可用；该脚本会自动记录最新命令和选项，便于在尝试新操作前快速查阅。

核心交互流程

1. 使用 playwright-cli open <url> 加载页面（如需隔离环境，可添加 --session=name）。
2. 执行 playwright-cli snapshot 生成元素引用（如 e1, e2, …），在任何交互前进行快照。DOM 变化或页面跳转后务必重新快照，避免引用失效。
3. 使用引用执行操作：

- click, dblclick, hover, drag, check, uncheck, select, fill, type, upload, eval

- 可附加 [button]、[value] 或 JavaScript 片段（例如：playwright-cli click e4 right）。

1. 使用以下命令捕获执行证据：

- screenshot [ref]：截图指定元素

- pdf：导出 PDF

- console [level]：查看控制台日志

- network：检查网络请求

1. 示例操作流：

playwright-cli open https://example.com/login
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "supersecret"
playwright-cli click e3
playwright-cli snapshot
playwright-cli screenshot

会话与持久化

• 使用 --session=<name> 可为每个工作流创建独立的会话，保留 Cookie、存储数据和标签页状态。会话行为类似持久化配置文件，可在命令间保持登录状态、浏览历史和标签页。
• 若在同一个会话中连续执行多个命令，可设置环境变量 PLAYWRIGHT_CLI_SESSION=mysession，CLI 将默认使用该会话，无需重复指定 --session。
• 显式管理会话：

playwright-cli session-list
playwright-cli session-stop <name>
playwright-cli session-stop-all
playwright-cli session-restart <name>
playwright-cli session-delete <name>

• 使用 playwright-cli --isolated open ... 启动临时上下文，不保存到磁盘。
• 当更改会话的浏览器设置（如启动参数、无头模式切换、浏览器选择）后，需重新运行 playwright-cli config 并执行 session-restart 以应用新配置。

标签页、导航与开发者工具

• 标签页操作：

- tab-list：列出当前所有标签页

- tab-new [url]：打开新标签页

- tab-close <index>：关闭指定索引的标签页

- tab-select <index>：切换至指定索引的标签页

• 导航快捷键：

- go-back：后退

- go-forward：前进

- reload：刷新页面

• 键盘与鼠标控制：

- press <key>：按下按键

- keydown：按下键

- keyup：释放键

- mousemove <x> <y>：移动鼠标指针

- mousedown [button]：按下鼠标按钮

- mouseup [button]：释放鼠标按钮

- mousewheel <dx> <dy>：滚动鼠标滚轮

• 开发者工具风格调试：

playwright-cli console [level]
playwright-cli network
playwright-cli run-code "async page => await page.context().grantPermissions(['clipboard-read'])"

可用于检查控制台输出、分析网络请求或注入辅助脚本。

录制、追踪与导出

• 对关键操作进行录制，以便后续回放：

playwright-cli tracing-start
# 执行操作步骤
playwright-cli tracing-stop
playwright-cli video-start
# 执行操作步骤
playwright-cli video-stop video.webm

• 使用 screenshot、pdf 或 snapshot 将结果保存至磁盘。生成的文件将遵循配置文件中的 outputDir 设置。

配置、状态与维护

• 使用 playwright-cli config 调整运行时参数，无需重新安装。示例：

playwright-cli config --headed --browser=firefox
playwright-cli --session=auth config --config=playwright-cli.json

修改 browser、contextOptions、launchOptions 或录制相关设置后，重启会话以生效。

• 运行 playwright-cli install 可更新浏览器二进制文件，适用于新环境或遇到缺失二进制文件的错误。

• 完成操作后清理会话，避免残留状态：

playwright-cli session-stop <name>
playwright-cli session-delete <name>

故障排查与提示

• 若命令执行失败，请重新运行 playwright-cli snapshot 确认元素引用仍有效。快照提供当前 DOM 上下文，用于 click、type 等操作。
• playwright-cli --help 始终显示最新命令列表，建议在使用不常用选项前查阅。
• 当需要复现手动操作流程时，应截取屏幕快照，记录会话名称，并注明所用元素引用和标签页。
• 如需可见浏览器界面（如人工检查），请通过 --headed 重新配置，或仅对特定会话执行 playwright-cli open --headed <url>。