Playwright 接入指南

本文提供从 REST API 启动环境 到 Playwright 连接 CDP 的最小可用流程。完整 API 见 API 概述；Python 长示例见自动化 API。

专业版

本地 API 与 api-key 需专业版会员，并在客户端 API 菜单查看实际端口。

流程概览

1. 获取 API 地址与密钥

启动 Virtual Browser 并登录有效会员。
打开 API 页面，记下：
- http://localhost:{port}（port 以界面为准）
- api-key

2. 启动浏览器环境

http

POST http://localhost:{port}/api/launchBrowser
Content-Type: application/json
api-key: YOUR_API_KEY

json

{ "id": 1 }

也可用 name 或 remark 定位环境，见启动浏览器。

成功响应中的 data.debuggingPort 即为 CDP 端口，例如 9222。

3. Playwright（Python）连接

python

import requests
from playwright.sync_api import sync_playwright

BASE = "http://localhost:9000"  # 替换为 API 页显示的 port
HEADERS = {"Content-Type": "application/json", "api-key": "YOUR_API_KEY"}

r = requests.post(f"{BASE}/api/launchBrowser", headers=HEADERS, json={"id": 1})
r.raise_for_status()
body = r.json()
if not body.get("success"):
    raise RuntimeError(body)

port = body["data"]["debuggingPort"]

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(f"http://127.0.0.1:{port}")
    context = browser.contexts[0] if browser.contexts else browser.new_context()
    page = context.pages[0] if context.pages else context.new_page()
    page.goto("https://example.com")
    print(page.title())

requests.post(f"{BASE}/api/stopBrowser", headers=HEADERS, json={"id": 1})

TIP

connect_over_cdp 应连接 launchBrowser 返回的 debuggingPort，不要另起独立 Chromium，否则会失去该环境的指纹与代理。

4. Playwright（Node.js）连接

javascript

import fetch from 'node-fetch';
import { chromium } from 'playwright';

const BASE = 'http://localhost:9000';
const headers = { 'Content-Type': 'application/json', 'api-key': 'YOUR_API_KEY' };

const launch = await fetch(`${BASE}/api/launchBrowser`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ id: 1 }),
}).then((r) => r.json());

if (!launch.success) throw new Error(JSON.stringify(launch));

const port = launch.data.debuggingPort;
const browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
const page = browser.contexts()[0]?.pages()[0] ?? (await browser.newContext()).newPage();
await page.goto('https://example.com');
console.log(await page.title());

await fetch(`${BASE}/api/stopBrowser`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ id: 1 }),
});

5. Puppeteer

Puppeteer 同样可通过 CDP 连接：

javascript

const puppeteer = require('puppeteer-core');
const browser = await puppeteer.connect({
  browserURL: `http://127.0.0.1:${debuggingPort}`,
});

6. 常见错误

错误	原因与处理
401 / 鉴权失败	检查 `api-key` 请求头；客户端 API 页复制最新密钥
连接被拒绝	端口错误或未启动环境；先 `launchBrowser`
`success: false`	环境 id 不存在或已在运行，见启动浏览器
Playwright 连上但无指纹	使用了 `chromium.launch()` 而非 `connect_over_cdp`
仅 VIP 可用	开通专业版并重新登录

Playwright 接入指南 ​

流程概览 ​

1. 获取 API 地址与密钥 ​

2. 启动浏览器环境 ​

3. Playwright（Python）连接 ​

4. Playwright（Node.js）连接 ​

5. Puppeteer ​

6. 常见错误 ​

相关文档 ​