编码代理
介绍
🌐 Introduction
Playwright 配备了 playwright-cli，这是一个为编码代理设计的浏览器自动化命令行接口。它通过简洁的 CLI 命令和可安装的技能提供高效的浏览器控制，使其非常适合需要在有限上下文窗口内平衡浏览器自动化、大型代码库和推断的代理。
🌐 Playwright comes with playwright-cli, a command-line interface for browser automation designed for coding agents. It provides token-efficient browser control through concise CLI commands and installable skills, making it ideal for agents that need to balance browser automation with large codebases and reasoning within limited context windows.
playwright-cli 对比 Playwright MCP
🌐 playwright-cli vs Playwright MCP
playwright-cli最适合 编码代理（Claude Code、GitHub Copilot 等），这些代理偏好高效使用令牌、基于技能的工作流程。CLI 命令可以避免将大型工具模式和冗长的可访问性树加载到模型上下文中。- MCP 最适合用于那些能够受益于持久状态和对页面结构进行迭代推断的专业代理循环，例如探索性自动化或长时间运行的自主工作流。参见 MCP 入门指南。
先决条件
🌐 Prerequisites
开始之前，请确保已安装以下软件：
🌐 Before you begin, make sure you have the following installed:
- Node.js 18 或更新版本
- 一个编码代理：Claude Code、GitHub Copilot 或类似工具
安装
🌐 Installation
全局安装 playwright-cli ：
🌐 Install playwright-cli globally:
npm install -g @playwright/cli@latest
playwright-cli --help
或者，将 @playwright/cli 安装为本地依赖并使用 npx：
🌐 Alternatively, install @playwright/cli as a local dependency and use npx:
npx playwright-cli --help
安装技能
🌐 Installing skills
像 Claude Code 和 GitHub Copilot 这样的编码代理可以使用本地安装的技能来获取有关可用命令的更丰富上下文：
🌐 Coding agents like Claude Code and GitHub Copilot can use locally installed skills for richer context about available commands:
playwright-cli install --skills
无需技能操作
🌐 Skills-less operation
你也可以直接将你的代理指向 CLI，让它自行发现命令：
🌐 You can also point your agent at the CLI directly and let it discover commands on its own:
Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.
第一步
🌐 First Steps
互动演示
🌐 Interactive demo
试着问问你的编码代理：
🌐 Try asking your coding agent:
Use playwright skills to test https://demo.playwright.dev/todomvc/.
Take screenshots for all successful and failing scenarios.
手动演练
🌐 Manual walkthrough
你也可以手动运行命令以查看 CLI 的工作原理：
🌐 You can also run commands manually to see how the CLI works:
playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli check e21
playwright-cli screenshot
每条命令执行后，CLI 会输出当前页面状态的快照：
🌐 After each command, the CLI outputs a snapshot of the current page state:
### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React • TodoMVC
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
核心命令
🌐 Core Commands
与页面互动
🌐 Interacting with pages
playwright-cli open [url] # open browser, optionally navigate to url
playwright-cli goto <url> # navigate to a url
playwright-cli click <ref> [button] # click an element
playwright-cli type <text> # type text into editable element
playwright-cli fill <ref> <text> # fill text into editable element
playwright-cli select <ref> <value> # select an option in a dropdown
playwright-cli check <ref> # check a checkbox or radio button
playwright-cli uncheck <ref> # uncheck a checkbox
playwright-cli hover <ref> # hover over element
playwright-cli drag <startRef> <endRef> # drag and drop between elements
playwright-cli upload <file> # upload files
playwright-cli close # close the page
目标元素
🌐 Targeting elements
使用快照中的元素引用来定位元素：
🌐 Use element refs from snapshots to target elements:
playwright-cli snapshot # get snapshot with element refs
playwright-cli click e15 # click using a ref
你也可以使用 CSS 或角色选择器：
🌐 You can also use CSS or role selectors:
playwright-cli click "#main > button.submit"
playwright-cli click "role=button[name=Submit]"
playwright-cli click "#footer >> role=button[name=Submit]"
屏幕截图和快照
🌐 Screenshots and snapshots
playwright-cli snapshot # capture page snapshot
playwright-cli snapshot --filename=f # save snapshot to specific file
playwright-cli screenshot # screenshot of the current page
playwright-cli screenshot [ref] # screenshot of a specific element
playwright-cli screenshot --filename=f # save with specific filename
playwright-cli pdf # save page as PDF
导航
🌐 Navigation
playwright-cli go-back # go back
playwright-cli go-forward # go forward
playwright-cli reload # reload the page
键盘和鼠标
🌐 Keyboard and mouse
playwright-cli press <key> # press a key (e.g. Enter, ArrowLeft)
playwright-cli keydown <key> # key down
playwright-cli keyup <key> # key up
playwright-cli mousemove <x> <y> # move mouse
playwright-cli mousedown [button] # mouse button down
playwright-cli mouseup [button] # mouse button up
playwright-cli mousewheel <dx> <dy> # scroll
标签
🌐 Tabs
playwright-cli tab-list # list all tabs
playwright-cli tab-new [url] # create a new tab
playwright-cli tab-select <index> # select a tab
playwright-cli tab-close [index] # close a tab
网络
🌐 Network
playwright-cli network # list network requests since page load
playwright-cli route <pattern> [opts] # mock network requests
playwright-cli route-list # list active routes
playwright-cli unroute [pattern] # remove routes
存储
🌐 Storage
playwright-cli state-save [filename] # save storage state (cookies, localStorage)
playwright-cli state-load <filename> # load storage state
# Cookies
playwright-cli cookie-list [--domain] # list cookies
playwright-cli cookie-get <name> # get a cookie
playwright-cli cookie-set <name> <val> # set a cookie
playwright-cli cookie-delete <name> # delete a cookie
playwright-cli cookie-clear # clear all cookies
# localStorage
playwright-cli localstorage-list # list entries
playwright-cli localstorage-get <key> # get value
playwright-cli localstorage-set <k> <v> # set value
playwright-cli localstorage-delete <k> # delete entry
playwright-cli localstorage-clear # clear all
DevTools
playwright-cli console [min-level] # list console messages
playwright-cli eval <func> [ref] # evaluate JavaScript on page
playwright-cli run-code <code> # run Playwright code snippet
playwright-cli tracing-start # start trace recording
playwright-cli tracing-stop # stop trace recording
playwright-cli video-start # start video recording
playwright-cli video-chapter <title> # add chapter marker to video
playwright-cli video-stop --filename=f # stop video recording
会话
🌐 Sessions
CLI 默认会将浏览器配置保存在内存中——会话内调用之间会保留 cookie 和存储状态，但浏览器关闭时会丢失。使用 --persistent 可以将配置保存到磁盘上。
🌐 The CLI keeps the browser profile in memory by default — cookies and storage state are preserved between calls within a session but lost when the browser closes. Use --persistent to save the profile to disk.
命名会话
🌐 Named sessions
为不同的项目运行多个浏览器实例：
🌐 Run multiple browser instances for different projects:
playwright-cli open https://playwright.nodejs.cn
playwright-cli -s=example open https://example.com --persistent
playwright-cli list # list all sessions
你可以配置你的编码代理以使用特定会话：
🌐 You can configure your coding agent to use a specific session:
PLAYWRIGHT_CLI_SESSION=todo-app claude .
会话管理
🌐 Session management
playwright-cli list # list all sessions
playwright-cli close-all # close all browsers
playwright-cli kill-all # forcefully kill all browser processes
playwright-cli -s=name delete-data # delete user data for a named session
监控
🌐 Monitoring
使用 playwright-cli show 打开可视化仪表板，以观察和控制所有正在运行的浏览器会话：
🌐 Use playwright-cli show to open a visual dashboard for observing and controlling all running browser sessions:
playwright-cli show
仪表板提供：
🌐 The dashboard provides:
- 会话网格 — 所有活跃会话按工作区分组，每个会话都带有实时屏幕投影预览、会话名称、当前网址和页面标题。点击任意会话即可放大查看。
- 会话详情 — 所选会话的实时视图，包含选项卡栏、导航控件和完整的远程控制。点击视口以接管鼠标和键盘；按下 Esc 键以释放。
配置
🌐 Configuration
有头模式
🌐 Headed mode
CLI 默认以无头模式运行。要查看浏览器：
🌐 The CLI runs headless by default. To see the browser:
playwright-cli open https://playwright.nodejs.cn --headed
浏览器选择
🌐 Browser selection
playwright-cli open --browser=chrome # use specific browser
playwright-cli open --browser=firefox
playwright-cli open --browser=webkit
playwright-cli open --browser=msedge
配置文件
🌐 Configuration file
对于高级设置，请使用 JSON 配置文件：
🌐 For advanced settings, use a JSON config file:
playwright-cli --config path/to/config.json open example.com
如果存在，CLI 也会自动加载 .playwright/cli.config.json。配置文件支持浏览器选项、上下文选项、网络规则、超时等更多设置。运行 playwright-cli --help 可查看完整的选项列表。
🌐 The CLI also loads .playwright/cli.config.json automatically if present. The config file supports browser options, context options, network rules, timeouts, and more. Run playwright-cli --help for the full list of options.
浏览器扩展
🌐 Browser extension
连接到你现有的浏览器标签页，而不是启动新的浏览器：
🌐 Connect to your existing browser tabs instead of launching a new browser:
playwright-cli open --extension
这需要安装 Playwright 扩展。
🌐 This requires the Playwright Extension to be installed.
快速参考
🌐 Quick Reference
| 操作 | 命令 |
|---|---|
| 安装 CLI | npm install -g @playwright/cli@latest |
| 安装技能 | playwright-cli install --skills |
| 打开页面 | playwright-cli open https://example.com |
| 点击元素 | playwright-cli click e15 |
| 输入文本 | playwright-cli type "hello world" |
| 截取屏幕截图 | playwright-cli screenshot |
| 获取页面快照 | playwright-cli snapshot |
| 以有界模式运行 | playwright-cli open https://example.com --headed |
| 使用 Firefox | playwright-cli open --browser=firefox |
| 监控会话 | playwright-cli show |
下一步是什么
🌐 What's Next