从 Browserless 迁移
Browserless 提供一个 WebSocket 地址供 Puppeteer 或 Playwright 连接,可以在它的云端,也可以在它的 Docker 镜像中。Clearcote 同样两种都支持,所以要改的只是代码连接的地址,页面代码保持不变。
从 Browserless 云端迁移
Browserless 的地址是固定的。Clearcote 的会话需要先创建,其 connectUrl 只能使用一次,因此唯一新增的步骤是在每次连接前调用一次创建接口。SDK 会在一次调用中完成这两步。
import puppeteer from "puppeteer-core";
async function connectUrl(options = {}) {
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
method: "POST",
headers: { authorization: "Bearer " + process.env.CLEARCOTE_API_KEY, "content-type": "application/json" },
body: JSON.stringify(options),
});
const { connectUrl, error } = await res.json();
if (error) throw new Error(error);
return connectUrl; // single-use: create one per connection
}
const browser = await puppeteer.connect({
browserWSEndpoint: "wss://production-sfo.browserless.io?token=" + process.env.BROWSERLESS_TOKEN,
browserWSEndpoint: await connectUrl({ identity: "acct-1", country: "us" }),
defaultViewport: null,
});
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close(); // ends the session在“API keys”页面获取密钥;SDK 会从 CLEARCOTE_API_KEY 读取它。浏览器在你连接时启动,通常几秒内就绪;指定 country 时最多可能需要半分钟左右,所以请给 Playwright 的 connectOverCDP 设置两分钟的 timeout。保留 defaultViewport: null,这样 Puppeteer 会沿用身份画像 (persona) 为浏览器设定的窗口大小。
URL 选项放到哪里
原来写在 Browserless URL 里的设置,改为放进创建调用的 JSON 请求体。Chromium 启动参数在托管模式下没有对应项:身份画像及其开关都已为你设置好。
| 你想要 | 创建请求体 |
|---|---|
| 某个国家的住宅出口 IP | "country": "de" (也可用 state、city);默认使用托管代理池 |
| 你自己的代理 | "proxy": { "server": "http://host:8080", "username": "…", "password": "…" } |
| 同一账号使用相同的 IP 和设备 | "identity": "acct-1" |
| 在会话之间保留 Cookie | "profile": { "name": "acct-1", "persist": true } |
| 会话时长限制 | "timeoutSec", "idleTimeoutSec" |
| 录像 | "record": true |
| 之后重新连接 | "keepAlive": true |
所有选项见选项与身份。Stealth 不是一条单独的路由:每个托管浏览器都在引擎层面运行身份画像,复选框、滑块和长按验证默认都会处理(验证)。没有 /content、/screenshot 或 /pdf 端点:用几行 Playwright 代码实现,或者描述任务并启动一个智能体任务,它会返回 JSON。
从 Browserless Docker 镜像迁移
clearcote serve 与开源镜像最接近:一个常驻端点,每个身份一个独立浏览器,设置写在连接 URL 里。
docker run -p 3000:3000 -e TOKEN=... ghcr.io/browserless/chromium
pip install -U clearcote # or: npm install -g clearcote
clearcote serve --port 9222 --idle-timeout 300 --max-browsers 16p.chromium.connect_over_cdp("http://127.0.0.1:9222") # one shared browser
p.chromium.connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-1&platform=windows") # a browser of its own
p.chromium.connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-2&proxy=http://user:pass@host:8080&geoip=true")如果每个容器只用一个身份,teamflatearth/clearcote 镜像会在 9222 端口提供 CDP;参见部署与 Docker。无论哪种方式,都只在可信网络中开放该端口:拿到 CDP 端口就等于完全控制了浏览器。同时运行多个浏览器以及使用带密码的代理需要许可证密钥:用 GitHub 登录可免费使用,同一时间一个浏览器;Pro 最多 250 个。