连接与断开

🌐 Attach & Detach

连接到现有的浏览器，而不是启动一个新的浏览器。

🌐 Connect to an existing browser instead of launching a new one.

命令

🌐 Commands

命令	描述
attach <name>	通过名称附加到已绑定的 Playwright 浏览器
attach --cdp=<channel>	通过通道名称连接到正在运行的浏览器
attach --cdp=<url>	通过 Chrome DevTools 协议端点连接
attach --endpoint=<url>	连接到 Playwright 服务器端点
attach --extension	通过 Playwright 扩展连接（默认使用 Chrome）
attach --extension=<channel>	通过 Playwright 扩展连接到特定通道
detach	关闭会话，但保留外部浏览器运行

只能给出一个目标——将位置名称与 --cdp、--endpoint 或 --extension 组合是错误的。

🌐 Exactly one target may be given — combining a positional name with --cdp, --endpoint, or --extension is an error.

找点东西可以依附

🌐 Finding something to attach to

playwright-cli list --all

除了开放的会话，这里还列出了在任何工作区中绑定的 Playwright 浏览器服务器和它找到的本地 Chrome/Edge 配置文件，每个都附有要使用的确切 attach 命令：

🌐 Alongside the open sessions, this lists the Playwright browser servers bound in any workspace and the local Chrome/Edge profiles it found, each with the exact attach command to use:

### Browsers available to attach via CDP

- chrome:
  - data-dir: /Users/me/Library/Application Support/Google/Chrome
  - attach (extension): `playwright-cli attach --extension=chrome`
  - attach (remote debugging): enable at chrome://inspect/#remote-debugging

按通道名称附加

🌐 Attach by channel name

通过其通道名称连接到正在运行的 Chrome 或 Edge 实例。浏览器必须启用远程调试——在目标浏览器中导航到 chrome://inspect/#remote-debugging 并勾选“允许此浏览器实例进行远程调试”。

🌐 Connect to a running Chrome or Edge instance by its channel name. The browser must have remote debugging enabled — navigate to chrome://inspect/#remote-debugging in the target browser and check "Allow remote debugging for this browser instance".

# Attach to Chrome
playwright-cli attach --cdp=chrome

# Attach to Chrome Canary
playwright-cli attach --cdp=chrome-canary

# Attach to Microsoft Edge
playwright-cli attach --cdp=msedge

# Attach to Edge Dev
playwright-cli attach --cdp=msedge-dev

支持的通道：chrome、chrome-beta、chrome-dev、chrome-canary、msedge、msedge-beta、msedge-dev、msedge-canary。

🌐 Supported channels: chrome, chrome-beta, chrome-dev, chrome-canary, msedge, msedge-beta, msedge-dev, msedge-canary.

这是最简单的连接方式——无需使用特殊标志启动 Chrome，也无需知道调试端口。

🌐 This is the simplest way to connect — no need to start Chrome with special flags or know the debugging port.

CDP 端点

🌐 CDP endpoint

连接到任何具有 Chrome DevTools 协议端点的基于 Chromium 的浏览器：

🌐 Connect to any Chromium-based browser with a Chrome DevTools Protocol endpoint:

# Start Chrome with remote debugging
google-chrome --remote-debugging-port=9222

# Connect from the CLI
playwright-cli attach --cdp=http://localhost:9222
playwright-cli snapshot
playwright-cli click e5

适用于：

🌐 Works with:

• 带有 --remote-debugging-port 的 Chrome / Chromium
• 启用远程调试的 Edge
• 暴露 CDP 的 Electron 应用
• 云浏览器服务（Browserbase 等）

Playwright 服务器端点

🌐 Playwright server endpoint

连接到远程 Playwright 服务器：

🌐 Connect to a remote Playwright server:

playwright-cli attach --endpoint=ws://localhost:3000
playwright-cli snapshot

按绑定名称附加

🌐 Attach by bound name

Playwright 浏览器可以以一个名字绑定自己——这就是 npx playwright test --debug=cli 暴露一个暂停测试的方式。将名字作为位置参数传入：

🌐 A Playwright browser can bind itself under a name — this is how npx playwright test --debug=cli exposes a paused test. Pass the name as a positional argument:

playwright-cli attach tw-a3f19c

请参见 测试调试。

🌐 See Test Debugging.

浏览器扩展

🌐 Browser extension

使用 Playwright 扩展 连接到你现有的浏览器标签页。这可以让你重用已登录的会话、Cookies 和已安装的扩展程序。

🌐 Connect to your existing browser tabs using the Playwright Extension. This lets you reuse your logged-in sessions, cookies, and installed extensions.

# Attach to Chrome (default)
playwright-cli attach --extension

# Attach to a specific channel
playwright-cli attach --extension=chrome-canary
playwright-cli attach --extension=msedge
playwright-cli attach --extension=msedge-dev

如果未指定通道，该扩展默认附加到 Chrome。

🌐 If no channel is specified, the extension attaches to Chrome by default.

何时使用扩展模式

🌐 When to use extension mode

• SSO / 2FA — 通过重复使用已认证的会话来跳过复杂的登录流程
• 浏览器扩展 — 与依赖已安装扩展的页面进行交互
• 已有标签页 — 自动化你已经打开的页面

会话命名

🌐 Session naming

Attach 会创建一个会话。当没有提供 --session 时，会话会以目标命名——--cdp=msedge 会创建一个名为 msedge 的会话，而 attach tw-a3f19c 会创建一个名为 tw-a3f19c 的会话——所以同时连接 Chrome 和 Edge 不会在 default 上冲突。

🌐 Attach creates a session. When --session is not given, the session is named after the target — --cdp=msedge creates a session called msedge, and attach tw-a3f19c creates one called tw-a3f19c — so parallel attaches to Chrome and Edge don't collide on default.

playwright-cli attach --cdp=chrome -s=debug-session
playwright-cli -s=debug-session snapshot
playwright-cli -s=debug-session click e5

分开

🌐 Detaching

detach 会在不操作所连接浏览器的情况下结束会话。close 仅用于 CLI 自己启动的浏览器。

playwright-cli detach                   # detach the default attached session
playwright-cli -s=msedge detach         # detach a named attached session

工作流：连接到正在运行的 Chrome

🌐 Workflow: connect to your running Chrome

# 1. In Chrome, go to chrome://inspect/#remote-debugging
#    and enable "Allow remote debugging for this browser instance"

# 2. Attach by channel name
playwright-cli attach --cdp=chrome

# 3. Interact with your existing tabs
playwright-cli snapshot
playwright-cli screenshot --filename=current-state.png

# 4. Save state for future headless sessions
playwright-cli state-save auth.json

# 5. Leave Chrome running
playwright-cli -s=chrome detach

工作流程：调试远程浏览器

🌐 Workflow: debugging a remote browser

# On the remote machine: start Chrome with debugging
google-chrome --remote-debugging-port=9222

# On your machine: connect via SSH tunnel
ssh -L 9222:localhost:9222 user@remote-host

# Attach and inspect
playwright-cli attach --cdp=http://localhost:9222
playwright-cli snapshot
playwright-cli screenshot --filename=remote-state.png
playwright-cli console error