oxylabs-headless-browser

Oxylabs 无头浏览器

远程无头浏览器服务，内置反检测功能并集成代理。Chrome 支持 Playwright、Puppeteer 和任何兼容 CDP 的库。Firefox 为旧版，使用 Playwright 的 Firefox 连接 API。

环境变量

Headless Browser 凭据优先使用 OXY_UNBLOCKER_USERNAME 和 OXY_UNBLOCKER_PASSWORD。旧配置也支持 OXY_HB_USERNAME 和 OXY_HB_PASSWORD 作为别名。

连接 URL

浏览器	全球端点	美国端点
Chrome	wss://USERNAME:[email protected]	wss://USERNAME:[email protected]
Firefox（旧版）	wss://USERNAME:[email protected]	wss://USERNAME:[email protected]

浏览器类型

类型	最适用于	说明
Chrome	高性能、专用服务器、住宅代理	使用 chromium.connect_over_cdp / connectOverCDP
Firefox（旧版）	在 Chrome 之外表现更好的目标网站所需的替代引擎	使用 firefox.connect；支持的 Playwright 版本为 1.51 和 1.56，通过 ?o_pw=1.56 指定

快速开始

Playwright（Python）：

from playwright.sync_api import sync_playwright
import os

username = os.environ.get("OXY_UNBLOCKER_USERNAME") or os.environ["OXY_HB_USERNAME"]
password = os.environ.get("OXY_UNBLOCKER_PASSWORD") or os.environ["OXY_HB_PASSWORD"]
endpoint = "ubc.oxylabs.io"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        f"wss://{username}:{password}@{endpoint}"
    )
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.content())
    browser.close()

Playwright（JavaScript）：

const { chromium } = require("playwright");

const username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;
const password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;
const endpoint = "ubc.oxylabs.io";

(async () => {
  const browser = await chromium.connectOverCDP(
    `wss://${username}:${password}@${endpoint}`
  );
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.content());
  await browser.close();
})();

Puppeteer：

const puppeteer = require("puppeteer");

const username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;
const password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;
const endpoint = "ubc.oxylabs.io";

(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: `wss://${username}:${password}@${endpoint}`
  });
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.content());
  await browser.close();
})();

速率限制

• **并发会话：**每种浏览器类型 100 个
• **启动速率：**每种浏览器类型每秒最多 10 个会话
• **更高限制：**可联系支持团队申请

功能

• **反检测：**内置指纹管理
• **住宅代理：**自动轮换代理
• **地理定位：**通过连接参数指定国家、城市和美国州
• **美国端点：**降低美国用户的延迟；这与代理地理位置并不相同
• **CAPTCHA 处理：**页面加载时自动求解；也可通过 window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*') 手动触发
• **会话检查：**使用 o_vnc=true 启用 VNC 调试
• **无需本地浏览器：**所有执行均在远程完成

连接参数

在 WebSocket URL 后追加查询参数：

参数	浏览器	说明
p_cc=US	Chrome、Firefox	通过 2 个字母的国家/地区代码路由流量
p_city=los_angeles	Chrome、Firefox	指定城市；与 p_cc 或 p_state 组合使用
p_state=texas	Chrome、Firefox	指定美国州；优先级高于 p_cc
p_device=mobile	Chrome	模拟 desktop、mobile 或 tablet 设备指纹
o_vnc=true	Chrome、Firefox	启用会话检查以进行可视化调试
o_pw=1.56	Firefox	选择受支持的 Firefox Playwright 版本 1.51 或 1.56
bargs=disable-notifications	Chrome	传入受支持的 Chrome 浏览器参数

支持的 Chrome bargs 值：force-color-profile:<profile>、window-position:X,Y、hide-scrollbars、enable-features:<feature1>,<feature2>、disable-notifications。

多个浏览器参数可重复使用 bargs，例如 ?bargs=force-color-profile:srgb&bargs=window-position:100,100。p_city 需要 p_cc 或 p_state；p_state 优先于 p_cc。

CAPTCHA 处理

• 监听 oxylabs-captcha-solve-start、oxylabs-captcha-solve-end 和 oxylabs-captcha-solve-error 窗口消息。
• 尽可能在导航前注册 CAPTCHA 监听器，以便捕获页面加载期间出现的验证。
• 对于页面加载后出现的 CAPTCHA，使用 window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*') 触发求解。
• 支持手动处理的 CAPTCHA 类型：hcaptcha、recaptcha、turnstile。

适用场景

场景	使用无头浏览器
复杂 JavaScript 网站	是
有反机器人保护的网站	是
具有隐身功能的浏览器自动化	是
截图/PDF 生成	是
简单 HTML 抓取	可考虑改用 Web Scraper API

支持的库

任何支持 Chrome DevTools Protocol（CDP）的库：

• Playwright（推荐）
• Puppeteer
• 使用 CDP 的 Selenium
• 自定义 CDP 实现

Firefox 已过时，应使用 Playwright firefox.connect，并搭配受支持的 Playwright 版本 1.51 或 1.56。

更多示例请参阅 examples.md。