如何在云端运行 Playwright?
- 启动浏览器。
POST /v1/agents(或 SDK 中的create_agent())会在 Browsa 云端启动一个 Phantom 浏览器,并返回它的id、cdp_http地址,以及一个可以打开观看的live_url。 - 连接。把
chromium.launch()换成chromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}),或把puppeteer.launch()换成puppeteer.connect({ browserURL, headers })。浏览器已经有一个上下文和一个打开的页面:直接用即可。 - 清理。用完后调用
destroy_agent(),或等 TTL 结束时浏览器自动关闭。按它实际运行的时间,每开始一个 12 分钟收 1 积分;预留的其余部分会退回。
你需要一个 Browsa API 密钥(以 agt_live_ 开头)。注册并验证邮箱即可获得 100 个免费积分,无需绑卡。无需在你的电脑或 Docker 镜像中安装 Chrome。
连接你的客户端
Python 版 Playwright
pip install browsa playwright无需运行 playwright install:浏览器运行在 Browsa 上。
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 playwrightimport { 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-coreimport { 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 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] 及其第一个页面,不要新建上下文。
生命周期
浏览器会一直运行到 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。
如何下载文件?
在页面内获取文件并返回字节:
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 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 地址。