介绍
# Clawbrowser – browser control via Playwright CLI [](https://clawaudit.duckdns.org/audit/f4d4fb45-ed25-4659-8235-2459d0dc8189) [](https://clawaudit.duckdns.org/audit/a55cb413-b111-4f1a-9f39-a5c857090ebf)
## 安装与概览 1. 安装 CLI 并验证可用性： ```bash npm install -g @playwright/cli@latest playwright-cli --help ``` CLI 默认以无头模式（headless）运行；当您需要查看 UI 时，请在 `open` 命令中添加 `--headed`，或在 `playwright-cli.json` 中将 `browser.launchOptions.headless` 设置为 `false`。 2. CLI 默认读取 `playwright-cli.json`，或者读取您通过 `--config` 传入的文件。使用配置文件可以调整浏览器名称、启动/上下文选项、视口、超时、输出目录和录制设置，而无需修改每条命令。 3. 保持 `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]` 或 JS 代码片段（例如 `playwright-cli click e4 right`）。 4. 使用 `screenshot [ref]`、`pdf`、`console [level]` 或 `network` 捕获输出证据，以证明流程或检查错误。 5. 示例流程： ```bash playwright-cli open https://example.com/login playwright-cli snapshot playwright-cli fill e1 "[email protected]" playwright-cli fill e2 "supersecret" playwright-cli click e3 playwright-cli snapshot playwright-cli screenshot ```
## 会话与持久化 - 使用 `--session=<name>` 可以在每个工作流中隔离 cookie、存储和标签页。会话的行为类似于持久化配置文件：它们会在命令之间记住身份验证状态、历史记录和标签页。 - 如果您在同一会话中运行许多命令，请导出 `PLAYWRIGHT_CLI_SESSION=mysession`——CLI 将默认使用该会话，而无需每次都传递 `--session`。 - 显式管理会话： ```bash 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>`。 - 开发工具风格的内省： ```bash playwright-cli console [level] playwright-cli network playwright-cli run-code "async page => await page.context().grantPermissions(['clipboard-read'])" ``` 使用这些命令可以检查控制台日志、检查网络请求或注入辅助脚本。
## 录制、追踪与导出 - 围绕敏感交互录制追踪和视频，以便稍后回放代理所执行的操作： ```bash playwright-cli tracing-start # perform steps playwright-cli tracing-stop playwright-cli video-start # perform steps playwright-cli video-stop video.webm ``` - 使用 `screenshot`、`pdf` 或 `snapshot`（用于转储元素引用）将证据保存到磁盘。录制的文件会遵循配置中的 `outputDir` 设置。
## 配置、状态与维护 - 使用 `playwright-cli config` 调整运行时标志而无需重新安装。例如： ```bash playwright-cli config --headed --browser=firefox playwright-cli --session=auth config --config=playwright-cli.json ``` 在配置中更改 `browser`、`contextOptions`、`launchOptions` 或录制设置，并重启会话以应用它们。 - 如果环境是新环境或收到关于缺少二进制文件的错误，运行 `playwright-cli install` 将刷新浏览器二进制文件。 - 完成后清理会话以避免状态陈旧： ```bash playwright-cli session-stop <name> playwright-cli session-delete <name> ```
## 故障排除与提醒 - 如果命令失败，请重新运行 `playwright-cli snapshot` 以确认引用仍然有效。快照为 `click`/`type` 操作提供当前的 DOM 上下文。 - `playwright-cli --help` 始终显示最新的命令集，因此在尝试不常用的标志之前请先查阅它。 - 当代理需要复现录制的手动流程时，请捕获屏幕截图，记下会话名称，并提及使用了哪些引用和标签页。 - 如果需要定向到可见的浏览器（例如手动检查），请使用 `--headed` 重新配置，或仅为该会话运行 `playwright-cli open --headed <url>`。