🚀 快速安装

复制以下命令并运行，立即安装此 Skill：

npx skills add https://skills.sh/microsoft/playwright-cli/dev

💡 提示：需要 Node.js 和 NPM

playwright-cli

带有 SKILLS 的 Playwright CLI

Playwright CLI vs Playwright MCP

此包提供了 Playwright 的 CLI 接口。如果您正在使用编码智能体，这是最佳选择。

  • CLI：现代编码智能体越来越倾向于将作为 SKILL 暴露的 CLI 工作流，而非 MCP，因为 CLI 调用更节省 token：它们避免将庞大的工具架构和冗长的可访问性树加载到模型上下文中，允许智能体通过简洁、目的明确的命令进行操作。这使得 CLI + SKILLs 更适合高吞吐量的编码智能体，这些智能体必须在有限的上下文窗口中平衡浏览器自动化与大型代码库、测试和推理。
  • MCP：MCP 仍然适用于那些受益于持久状态、丰富内省和对页面结构迭代推理的专业智能体循环，例如探索性自动化、自愈测试或长期运行的自主动工作流，在这些场景中，维持连续的浏览器上下文比 token 成本更重要。了解更多关于 Playwright MCP 的信息。

主要特性

  • 节省 Token。不强制将页面数据传入 LLM。

系统要求

  • Node.js 18 或更新版本
  • Claude Code、GitHub Copilot 或任何其他编码智能体。

快速开始

安装

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

安装 skills

Claude Code、GitHub Copilot 和其他工具将使用本地安装的 skills。

playwright-cli install --skills

无 Skills 操作

将您的智能体指向 CLI，让它自行发挥。它会自行读取 playwright-cli --help 中的技能说明：

使用 playwright-cli 测试 https://demo.playwright.dev/todomvc 上的“添加待办事项”流程。
查看 playwright-cli --help 以获取可用命令。

演示

> 使用 playwright skills 测试 https://demo.playwright.dev/todomvc/。
  为所有成功和失败的场景截图。

您的智能体将运行命令，但这并不意味着您不能手动操作：

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "购买杂货"
playwright-cli press Enter
playwright-cli type "浇花"
playwright-cli press Enter
playwright-cli check e21
playwright-cli check e35
playwright-cli screenshot

有头模式操作

Playwright CLI 默认是无头模式。如果您想看到浏览器窗口，请在 open 命令中传递 --headed：

playwright-cli open https://playwright.dev --headed

会话 (Sessions)

Playwright CLI 默认将浏览器配置文件保存在内存中。在会话期间的 CLI 调用之间，您的 cookie 和存储状态会被保留，但在浏览器关闭时会丢失。使用 --persistent 将配置文件保存到磁盘，以便在浏览器重启后仍能保持持久化。

您可以通过会话为不同项目使用不同的浏览器实例。在调用时传递 -s= 与特定浏览器通信。

playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list

您可以通过 PLAYWRIGHT_CLI_SESSION 环境变量运行您的编码智能体：

PLAYWRIGHT_CLI_SESSION=todo-app claude .

或指示它在调用前添加 -s=。

按如下方式管理您的会话：

playwright-cli list                     # 列出所有会话
playwright-cli close-all                # 关闭所有浏览器
playwright-cli kill-all                 # 强制终止所有浏览器进程

监控

使用 playwright-cli show 打开一个可视化仪表板，让您查看和控制所有正在运行的浏览器会话。当您的编码智能体在后台运行浏览器自动化时，这非常有用，您可以在其中观察进度或介入帮助。

playwright-cli show

仪表板打开一个窗口，包含两个视图：

  • 会话网格 — 按工作区分组显示所有活动会话，每个会话都有实时屏幕预览、会话名称、当前 URL 和页面标题。单击任何会话可放大查看。
  • 会话详情 — 显示所选会话的实时视图，带有选项卡栏、导航控件（后退、前进、刷新、地址栏）和完整的远程控制功能。单击视口区域可接管鼠标和键盘输入；按 Escape 键释放控制。

在网格视图中，您还可以关闭正在运行的会话或删除非活动会话的数据。

命令

核心命令

playwright-cli open [url]               # 打开浏览器，可选择导航到 url
playwright-cli goto <url>               # 导航到 url
playwright-cli close                    # 关闭页面
playwright-cli type <text>              # 在可编辑元素中输入文本
playwright-cli click <ref> [button]     # 在网页上执行点击
playwright-cli dblclick <ref> [button]  # 在网页上执行双击
playwright-cli fill <ref> <text>        # 填充可编辑元素文本
playwright-cli drag <startRef> <endRef> # 在两个元素之间执行拖放
playwright-cli hover <ref>              # 悬停在页面元素上
playwright-cli select <ref> <val>       # 在下拉菜单中选择一个选项
playwright-cli upload <file>            # 上传一个或多个文件
playwright-cli check <ref>              # 勾选复选框或单选按钮
playwright-cli uncheck <ref>            # 取消勾选复选框或单选按钮
playwright-cli snapshot                 # 捕获页面快照以获取元素引用
playwright-cli snapshot --filename=f    # 将快照保存到特定文件
playwright-cli eval <func> [ref]        # 在页面或元素上执行 JavaScript 表达式
playwright-cli dialog-accept [prompt]   # 接受对话框
playwright-cli dialog-dismiss           # 关闭对话框
playwright-cli resize <w> <h>           # 调整浏览器窗口大小

导航

playwright-cli go-back                  # 返回上一页
playwright-cli go-forward               # 前进到下一页
playwright-cli reload                   # 重新加载当前页面

键盘

playwright-cli press <key>              # 按下键盘按键，如 `a`，`arrowleft`
playwright-cli keydown <key>            # 按下键盘按键（不释放）
playwright-cli keyup <key>              # 释放键盘按键

鼠标

playwright-cli mousemove <x> <y>        # 移动鼠标到指定位置
playwright-cli mousedown [button]       # 按下鼠标按键
playwright-cli mouseup [button]         # 释放鼠标按键
playwright-cli mousewheel <dx> <dy>     # 滚动鼠标滚轮

另存为

playwright-cli screenshot [ref]         # 截取当前页面或元素的屏幕截图
playwright-cli screenshot --filename=f  # 使用指定文件名保存屏幕截图
playwright-cli pdf                      # 将页面保存为 pdf
playwright-cli pdf --filename=page.pdf  # 使用指定文件名保存 pdf

标签页

playwright-cli tab-list                 # 列出所有标签页
playwright-cli tab-new [url]            # 创建新标签页
playwright-cli tab-close [index]        # 关闭浏览器标签页
playwright-cli tab-select <index>       # 选择浏览器标签页

存储

playwright-cli state-save [filename]    # 保存存储状态
playwright-cli state-load <filename>    # 加载存储状态

# Cookies
playwright-cli cookie-list [--domain]   # 列出 cookies
playwright-cli cookie-get <name>        # 获取 cookie
playwright-cli cookie-set <name> <val>  # 设置 cookie
playwright-cli cookie-delete <name>     # 删除 cookie
playwright-cli cookie-clear             # 清除所有 cookies

# LocalStorage
playwright-cli localstorage-list        # 列出 localStorage 条目
playwright-cli localstorage-get <key>   # 获取 localStorage 值
playwright-cli localstorage-set <k> <v> # 设置 localStorage 值
playwright-cli localstorage-delete <k>  # 删除 localStorage 条目
playwright-cli localstorage-clear       # 清除所有 localStorage

# SessionStorage
playwright-cli sessionstorage-list      # 列出 sessionStorage 条目
playwright-cli sessionstorage-get <k>   # 获取 sessionStorage 值
playwright-cli sessionstorage-set <k> <v> # 设置 sessionStorage 值
playwright-cli sessionstorage-delete <k>  # 删除 sessionStorage 条目
playwright-cli sessionstorage-clear     # 清除所有 sessionStorage

网络

playwright-cli route <pattern> [opts]   # 模拟网络请求
playwright-cli route-list               # 列出活跃的路由
playwright-cli unroute [pattern]        # 移除路由

开发者工具

playwright-cli console [min-level]      # 列出控制台消息
playwright-cli network                  # 列出页面加载以来的所有网络请求
playwright-cli run-code <code>          # 运行 playwright 代码片段
playwright-cli tracing-start            # 开始录制 trace
playwright-cli tracing-stop             # 停止录制 trace
playwright-cli video-start              # 开始录制视频
playwright-cli video-stop [filename]    # 停止录制视频

Open 参数

playwright-cli open --browser=chrome    # 使用特定浏览器
playwright-cli open --extension         # 通过浏览器扩展连接
playwright-cli open --persistent        # 使用持久化配置文件
playwright-cli open --profile=<path>    # 使用自定义配置文件目录
playwright-cli open --config=file.json  # 使用配置文件
playwright-cli close                    # 关闭浏览器
playwright-cli delete-data              # 删除默认会话的用户数据

快照 (Snapshots)

每次命令执行后，playwright-cli 都会提供当前浏览器状态的快照。

> playwright-cli goto https://example.com
### 页面
- 页面 URL: https://example.com/
- 页面标题: Example Domain
### 快照
[快照](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)

您也可以使用 playwright-cli snapshot 命令按需拍摄快照。

如果没有提供 --filename，则会创建一个带有时间戳的新快照文件。默认使用自动文件命名，当产物是工作流结果的一部分时，请使用 --filename=。

会话

playwright-cli -s=name <cmd>            # 在命名会话中运行命令
playwright-cli -s=name close            # 停止命名浏览器
playwright-cli -s=name delete-data      # 删除命名浏览器的用户数据
playwright-cli list                     # 列出所有会话
playwright-cli close-all                # 关闭所有浏览器
playwright-cli kill-all                 # 强制终止所有浏览器进程

本地安装

在某些情况下，您可能想要本地安装 playwright-cli。如果全局可用的 playwright-cli 二进制文件无法运行，请使用 npx playwright-cli 来运行命令。例如：

npx playwright-cli open https://example.com
npx playwright-cli click e1

配置文件

Playwright CLI 可以使用 JSON 配置文件进行配置。您可以使用 --config 命令行选项指定配置文件：

playwright-cli --config path/to/config.json open example.com

Playwright CLI 默认会从 .playwright/cli.config.json 加载配置，这样您就不需要每次都指定它。

配置文件结构 
{
  /**
   * 要使用的浏览器。
   */
  browser?: {
    /**
     * 要使用的浏览器类型。
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

    /**
     * 将浏览器配置文件保存在内存中，不保存到磁盘。
     */
    isolated?: boolean;

    /**
     * 用于浏览器配置文件持久化的用户数据目录路径。
     * 默认创建临时目录。
     */
    userDataDir?: string;

    /**
     * 传递给浏览器的启动选项
     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
     *
     * 这对于设置 `channel`、`headless`、`executablePath` 等选项非常有用。
     */
    launchOptions?: playwright.LaunchOptions;

    /**
     * 浏览器上下文的上下文选项。
     *
     * 这对于设置 `viewport` 等选项非常有用。
     */
    contextOptions?: playwright.BrowserContextOptions;

    /**
     * Chrome DevTools Protocol 端点，用于连接现有的浏览器实例（适用于 Chromium 系列浏览器）。
     */
    cdpEndpoint?: string;

    /**
     * 随连接请求发送的 CDP 头部信息。
     */
    cdpHeaders?: Record<string, string>;

    /**
     * 连接 CDP 端点的超时时间（毫秒）。默认为 30000（30 秒）。传递 0 禁用超时。
     */
    cdpTimeout?: number;

    /**
     * 远程端点，用于连接现有的 Playwright 服务器。
     */
    remoteEndpoint?: string;

    /**
     * 要作为 Playwright 页面初始化脚本添加的 TypeScript 文件路径。
     */
    initPage?: string[];

    /**
     * 要添加为初始化脚本的 JavaScript 文件路径。
     * 这些脚本将在每个页面的任何页面脚本之前执行。
     */
    initScript?: string[];
  },

  /**
   * 如果指定，将 Playwright 视频保存到输出目录。
   */
  saveVideo?: {
    width: number;
    height: number;
  };

  /**
   * 保存输出文件的目录。
   */
  outputDir?: string;

  /**
   * 是否将快照、控制台消息、网络日志和其他会话日志保存到文件或标准输出。默认为 "stdout"。
   */
  outputMode?: 'file' | 'stdout';

  console?: {
    /**
     * 要返回的控制台消息级别。每个级别都包含更严重级别的消息。默认为 "info"。
     */
    level?: 'error' | 'warning' | 'info' | 'debug';
  },

  network?: {
    /**
     * 允许浏览器请求的源列表。默认允许所有。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
     */
    allowedOrigins?: string[];

    /**
     * 阻止浏览器请求的源列表。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
     */
    blockedOrigins?: string[];
  };

  /**
   * 指定用于测试 ID 的属性，默认为 "data-testid"。
   */
  testIdAttribute?: string;

  timeouts?: {
    /*
     * 配置默认操作超时时间：https://playwright.dev/docs/api/class-page#page-set-default-timeout。默认为 5000ms。
     */
    action?: number;

    /*
     * 配置默认导航超时时间：https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout。默认为 60000ms。
     */
    navigation?: number;
  };

  /**
   * 是否允许从文件系统的任何位置上传文件。
   * 默认情况下（false），文件上传仅限于 MCP 根目录内的路径。
   */
  allowUnrestrictedFileAccess?: boolean;

  /**
   * 指定用于代码生成的语言。
   */
  codegen?: 'typescript' | 'none';
}
环境变量配置

 

环境变量
PLAYWRIGHT_MCP_ALLOWED_HOSTS 允许此服务器提供服务的逗号分隔的主机列表。默认为服务器绑定的主机。传递 ‘*’ 以禁用主机检查。
PLAYWRIGHT_MCP_ALLOWED_ORIGINS 允许浏览器请求的受信任源的分号分隔列表。默认允许所有。重要提示：不作为安全边界，不影响重定向。
PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS 允许访问工作区根目录之外的文件。还允许不受限制地访问 file:// URL。默认情况下，对文件系统的访问仅限于工作区根目录（如果没有配置根目录，则限于当前工作目录），并且阻止导航到 file:// URL。
PLAYWRIGHT_MCP_BLOCKED_ORIGINS 阻止浏览器请求的源的分号分隔列表。阻止列表在允许列表之前评估。如果未使用允许列表，则不匹配阻止列表的请求仍然允许。重要提示：不作为安全边界，不影响重定向。
PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS 阻止 service workers
PLAYWRIGHT_MCP_BROWSER 要使用的浏览器或 Chrome 渠道，可能的值：chrome, firefox, webkit, msedge。
PLAYWRIGHT_MCP_CAPS 要启用的额外功能的逗号分隔列表，可能的值：vision, pdf。
PLAYWRIGHT_MCP_CDP_ENDPOINT 要连接的 CDP 端点。
PLAYWRIGHT_MCP_CDP_HEADERS 随连接请求发送的 CDP 头部信息，可以指定多个。
PLAYWRIGHT_MCP_CDP_TIMEOUT CDP 连接的超时时间。
PLAYWRIGHT_MCP_CONFIG 配置文件的路径。
PLAYWRIGHT_MCP_CONSOLE_LEVEL 要返回的控制台消息级别：”error”, “warning”, “info”, “debug”。每个级别都包含更严重级别的消息。
PLAYWRIGHT_MCP_DEVICE 要模拟的设备，例如：”iPhone 15″
PLAYWRIGHT_MCP_EXECUTABLE_PATH 浏览器可执行文件的路径。
PLAYWRIGHT_MCP_EXTENSION 连接到正在运行的浏览器实例（仅限 Edge/Chrome）。需要安装 “Playwright MCP Bridge” 浏览器扩展。\2

特定任务

已安装的技能包括针对常见任务的详细参考指南：

  • 请求模拟 — 拦截和模拟网络请求
  • 运行 Playwright 代码 — 执行任意 Playwright 脚本
  • 浏览器会话管理 — 管理多个浏览器会话
  • 存储状态（cookies, localStorage） — 持久化和恢复浏览器状态
  • 测试生成 — 从交互生成 Playwright 测试
  • 追踪 — 记录和检查执行追踪
  • 视频录制 — 捕获浏览器会话视频

📄 原始文档

完整文档（英文）：

https://skills.sh/microsoft/playwright-cli/dev

💡 提示：点击上方链接查看 skills.sh 原始英文文档，方便对照翻译。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。