跳到正文
Browsa
  1. 指南
  2. Playwright 和 Puppeteer

通过 CDP 把 Playwright 或 Puppeteer 连接到云浏览器。

基于 CDP 的云浏览器,是运行在别人服务器上、支持 Chrome DevTools Protocol 的真实浏览器,因此你的 Playwright 或 Puppeteer 代码可以像驱动本地浏览器一样驱动它。在 Browsa 上,一次 API 调用就能启动浏览器并返回它的 CDP 地址;你只需修改启动浏览器的那一行,脚本其余部分保持不变。

耗时
约 5 分钟
费用
浏览器时间每开始一个 12 分钟收 1 积分,整整 1 小时 5 积分
兼容
Playwright(Python、Node)、Puppeteer、任何 CDP 客户端

如何在云端运行 Playwright?

  1. 启动浏览器。POST /v1/agents(或 SDK 中的 create_agent())会在 Browsa 云端启动一个 Phantom 浏览器,并返回它的 id、cdp_http 地址,以及一个可以打开观看的 live_url。
  2. 连接。把 chromium.launch() 换成 chromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}),或把 puppeteer.launch() 换成 puppeteer.connect({ browserURL, headers })。浏览器已经有一个上下文和一个打开的页面:直接用即可。
  3. 清理。用完后调用 destroy_agent(),或等 TTL 结束时浏览器自动关闭。按它实际运行的时间,每开始一个 12 分钟收 1 积分;预留的其余部分会退回。

你需要一个 Browsa API 密钥(以 agt_live_ 开头)。注册并验证邮箱即可获得 100 个免费积分,无需绑卡。无需在你的电脑或 Docker 镜像中安装 Chrome。

连接你的客户端

Python 版 Playwright

终端
pip install browsa playwright

无需运行 playwright install:浏览器运行在 Browsa 上。

cloud_playwright.py
import os

from browsa import Client
from playwright.sync_api import sync_playwright

API_KEY = os.environ["BROWSA_API_KEY"]
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m")  # a cloud browser, up to 10 minutes

try:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(
            agent["cdp_http"], headers={"X-API-Key": API_KEY}
        )
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(page.title())
        # the rest is plain Playwright
finally:
    client.destroy_agent(agent["id"])

TypeScript 或 Node 版 Playwright

终端
npm i browsa playwright
cloud-playwright.ts
import { Client } from "browsa";
import { chromium } from "playwright";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });

try {
  const browser = await chromium.connectOverCDP(agent.cdp_http, {
    headers: { "X-API-Key": apiKey },
  });
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await client.destroyAgent(agent.id);
}

Puppeteer

使用 puppeteer-core。它的 API 与 puppeteer 相同,但不会下载浏览器,而你已经不需要本地浏览器了。

终端
npm i browsa puppeteer-core
cloud-puppeteer.ts
import { Client } from "browsa";
import puppeteer from "puppeteer-core";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "5m" });

try {
  const browser = await puppeteer.connect({
    browserURL: agent.cdp_http,
    headers: { "X-API-Key": apiKey },
  });
  const [page] = await browser.pages();
  await page.goto("https://example.com");
  console.log(await page.title());
  await browser.disconnect();
} finally {
  await client.destroyAgent(agent.id);
}

原生 CDP 和其他客户端

创建接口的响应中有两个地址。cdp_http 是浏览器的 HTTP 端点,也就是 Playwright 和 Puppeteer 需要的地址。cdp_url 是单个页面的 WebSocket,供直接使用 CDP 的客户端使用。两者都需要在 X-API-Key 请求头中带上密钥。任何能通过 CDP 并携带自定义请求头连接到现有浏览器的库,都可以使用同一个地址,browser-use 和 Stagehand 指南就是这样做的。

不用 SDK 的话,用普通 HTTP 启动浏览器:

curl
curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl": "10m", "initial_url": "https://example.com"}'

# -> { "id": "agt_…", "status": "running", "cdp_http": "https://browsa.io/api/v1/cdp/…",
#      "cdp_url": "wss://browsa.io/api/v1/cdp/…/ws/page/…", "live_url": "…", "cost_credits": 5 }

cost_credits 是浏览器运行期间预扣的积分:TTL 不超过 5 分钟为 1 积分,更长则为 5 积分。结束后,未用到的 12 分钟计费块会退回你的余额。

和本地浏览器有哪些不同?

视口和 user agent

屏幕尺寸、user agent、时区、语言、地理位置和 CPU 核数在浏览器启动时统一设定。单独修改其中某一项的 CDP 模拟命令会返回成功,但什么也不会改变,所以 page.set_viewport_size()、page.setViewport() 和 page.setUserAgent() 都不起作用。

怎么做向 POST /v1/agents 传入 screen_resolution 和 os_type。如果想自己控制模拟,在 CDP 地址的查询参数中加上 cdp_overrides=allow;此时保持指纹一致就要靠你自己了。

上下文和页面

浏览器启动时已带有一个上下文和一个打开的页面。

怎么做使用 browser.contexts[0] 及其第一个页面,不要新建上下文。

文件下载

下载的文件留在云浏览器中,Playwright 的下载事件会报告 canceled。

怎么做在页面内获取文件(见下文),这样会使用浏览器的 Cookie 和 IP 地址。

生命周期

浏览器会一直运行到 TTL 结束(最长 1 小时)或被你销毁为止,不会因空闲而结束。

怎么做按需申请 TTL("5m" 到 "1h")。更长的任务就启动新的浏览器,或使用保存的身份在它们之间保留登录状态。

网络

不配置代理时,流量从 Browsa 的数据中心发出,使用数据中心 IP 地址。

怎么做在 proxy 中传入 Browsa 网络({"network": "residential"})或你自己的 HTTP、HTTPS 或 SOCKS5 代理,或在 proxy_id 中传入已保存的代理。

自动化特征

Playwright 和 Puppeteer 在连接时会开启 CDP 的 Runtime 域,部分机器人检测能察觉到这一点。

怎么做如果网站标记了你的客户端,可以试试不调用 Runtime.enable 的原生 CDP 客户端,或使用 Browsa 自己的任务智能体(POST /v1/tasks)。带日期的结果见基准测试页面。

并行浏览器

每个工作区 6 个浏览器槽位。槽位全部占满时,请求返回 429 和 Retry-After: 30,不会扣费。

怎么做在你这边排队处理,或发邮件至 support@browsa.io 申请更多槽位。

连接断开后如何重新连接?

关闭 Playwright 或 Puppeteer 连接不会停止浏览器。它会一直运行到 TTL 结束,因此其他进程可以连接上去。用 GET /v1/agents/{id}/cdp(Python 中为 get_agent(agent_id),TypeScript 中为 getAgent(agentId))重新获取地址,并用同样的 X-API-Key 请求头连接。如果浏览器已不再运行,该端点返回 409。

如何下载文件?

在页面内获取文件并返回字节:

Python
import base64

b64 = page.evaluate("""async (url) => {
  const buf = new Uint8Array(await (await fetch(url)).arrayBuffer());
  let s = ""; for (const b of buf) s += String.fromCharCode(b);
  return btoa(s);
}""", "https://example.com/report.pdf")
open("report.pdf", "wb").write(base64.b64decode(b64))

如何使用自己的代理?

启动浏览器时加上一个 proxy 对象。浏览器会使用代理的 IP 地址;设置 country 后,时区和语言也会跟随该国家。代理流量在 Browsa 上不额外收费。

curl
curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": "10m",
    "proxy": {"type": "http", "host": "proxy.example.com", "port": 8080,
              "username": "your-proxy-user", "password": "your-proxy-password"},
    "country": "de"
  }'

即使代理无法连通,直接启动的浏览器也会照常启动,所以请先检查代理。已保存的代理有检查端点,并可通过 proxy_id 传入。

如何在多次运行之间保留登录状态?

用持久身份代替一次性浏览器。它会在多次会话之间保留 Cookie、本地存储和指纹。用 "mode": "persistent" 创建一次,之后脚本需要时就开启一个会话:POST /v1/agents/{id}/sessions 返回的结构与新浏览器相同,包括 cdp_http,连接方式和上面完全一样。每个身份每 30 天 50 积分,每个会话 1 积分。见开启会话。

费用是多少?

运行内容积分
运行不超过 12 分钟的浏览器1
运行整整 1 小时的浏览器5
持久身份,每 30 天50
持久身份上的会话(最长 1 小时)1
启动失败的浏览器退回

$20 的 Starter 包中 1 积分为 $0.10,更大的积分包更便宜。积分永不过期。完整价格。

故障排查

连接时出现 401 Unauthorized

X-API-Key 请求头没有送达 Browsa,或密钥有误。请按示例在连接调用中发送它,并确认密钥以 agt_ 开头。

启动浏览器时出现 402

INSUFFICIENT_CREDIT 表示余额不够支付你申请的 TTL;BUDGET_REACHED 表示已达到每月支出上限。请查看 GET /v1/credits 和 GET /v1/budget。

连接几分钟后断开

浏览器到了 TTL 结束的时间。请申请更长的 TTL,最长 "1h"。

常见问题

为什么 set_viewport_size() 改变不了浏览器?

Browsa 浏览器的屏幕尺寸、user agent、时区、语言和地理位置在创建时统一设定,让页面看到的是一台前后一致的机器。单独修改其中某一项的 CDP 模拟命令会返回成功,但什么也不会改变。请在创建浏览器时设置 screen_resolution 和 os_type;如果想自己控制模拟,在 CDP 地址中加上 cdp_overrides=allow。

如何从云浏览器下载文件?

页面下载的文件留在云浏览器中,Playwright 会把下载报告为已取消。请在页面内用 page.evaluate() 获取文件,这样会使用浏览器的 Cookie 和 IP 地址,再把字节以 base64 返回。

可以同时运行多少个浏览器?

每个工作区有 6 个浏览器槽位。每个运行中的浏览器占一个,每个保存的身份也占一个。槽位全部占满时,新建浏览器会返回 429 TOO_MANY_REQUESTS 和 Retry-After: 30,不会扣费。需要更多请发邮件至 support@browsa.io。

Browsa 提供代理吗?

提供。数据中心代理每 GB 5 积分,住宅代理每 GB 50 积分。也可以为每个浏览器传入你自己的 HTTP、HTTPS 或 SOCKS5 代理,免费。不配置代理时,浏览器使用 Browsa 数据中心的 IP 地址。

下一步

在云浏览器上运行你的脚本。

100 个免费积分。无需绑卡,无需订阅。