headless-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oxylabs Headless Browser

Oxylabs 无头浏览器

Remote headless browser service with built-in anti-detection and proxy integration. Chrome supports Playwright, Puppeteer, and any CDP-compatible library. Firefox is legacy and uses Playwright's Firefox connection API.

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

Environment Variables

环境变量

Prefer

OXY_UNBLOCKER_USERNAME

and

OXY_UNBLOCKER_PASSWORD

for Headless Browser credentials.

OXY_HB_USERNAME

and

OXY_HB_PASSWORD

are supported aliases in older setups.

无头浏览器凭证优先使用

OXY_UNBLOCKER_USERNAME

和

OXY_UNBLOCKER_PASSWORD

。在旧版配置中，

OXY_HB_USERNAME

和

OXY_HB_PASSWORD

作为别名也受支持。

Connection URLs

连接URL

Browser	Global endpoint	US endpoint
Chrome	`wss://USERNAME:PASSWORD@ubc.oxylabs.io`	`wss://USERNAME:PASSWORD@ubc-us.oxylabs.io`
Firefox (legacy)	`wss://USERNAME:PASSWORD@ubs.oxylabs.io`	`wss://USERNAME:PASSWORD@ubs-us.oxylabs.io`

浏览器	全球端点	美国端点
Chrome	`wss://USERNAME:PASSWORD@ubc.oxylabs.io`	`wss://USERNAME:PASSWORD@ubc-us.oxylabs.io`
Firefox（旧版）	`wss://USERNAME:PASSWORD@ubs.oxylabs.io`	`wss://USERNAME:PASSWORD@ubs-us.oxylabs.io`

Browser Types

浏览器类型

Type	Best For	Notes
Chrome	High performance, dedicated servers, residential proxies	Use `chromium.connect_over_cdp` / `connectOverCDP`
Firefox (legacy)	Alternative engine for targets that perform better outside Chrome	Use `firefox.connect` ; supported Playwright versions are 1.51 and 1.56 via `?o_pw=1.56`

类型	适用场景	说明
Chrome	高性能、专用服务器、住宅代理	使用 `chromium.connect_over_cdp` / `connectOverCDP`
Firefox（旧版）	针对在Chrome外表现更好的目标场景	使用 `firefox.connect` ；支持的Playwright版本为1.51和1.56，可通过 `?o_pw=1.56` 指定

Quick Start

快速开始

Playwright (Python):

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):

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:

javascript

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();
})();

Playwright（Python）：

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）：

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：

javascript

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();
})();

Rate Limits

速率限制

Concurrent sessions: 100 per browser type
Launch rate: up to 10 sessions per second per browser type
Higher limits: Available upon request to support

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

Features

功能特性

Anti-detection: Built-in fingerprint management
Residential proxies: Automatic proxy rotation
Geo-targeting: Country, city, and US state targeting via connection parameters
US endpoints: Lower latency for US-based users; not the same as proxy geolocation
CAPTCHA handling: Automatic load-time solving; manual trigger available with
```
window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*')
```
Session inspection: Enable VNC debugging with
```
o_vnc=true
```
No local browsers: All execution happens remotely

反检测： 内置指纹管理
住宅代理： 自动代理轮换
地理定位： 通过连接参数实现国家、城市和美国州级定位
美国端点： 为美国用户提供更低延迟；与代理地理位置不同

CAPTCHA处理： 自动解决加载时的验证；可通过

window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*')

手动触发

会话检查： 添加
```
o_vnc=true
```
参数启用VNC调试
无需本地浏览器： 所有执行均在远程完成

Connection Parameters

连接参数

Append query parameters to the WebSocket URL:

Parameter	Browser	Description
`p_cc=US`	Chrome, Firefox	Route traffic through a 2-letter country code
`p_city=los_angeles`	Chrome, Firefox	Target a city; combine with `p_cc` or `p_state`
`p_state=texas`	Chrome, Firefox	Target a US state; takes priority over `p_cc`
`p_device=mobile`	Chrome	Emulate `desktop` , `mobile` , or `tablet` device fingerprints
`o_vnc=true`	Chrome, Firefox	Enable Session Inspection for visual debugging
`o_pw=1.56`	Firefox	Select supported Firefox Playwright version `1.51` or `1.56`
`bargs=disable-notifications`	Chrome	Pass supported Chrome browser arguments

Supported Chrome

bargs

values:

force-color-profile:<profile>

window-position:X,Y

hide-scrollbars

enable-features:<feature1>,<feature2>

disable-notifications

Repeat

bargs

for multiple browser arguments, e.g.,

?bargs=force-color-profile:srgb&bargs=window-position:100,100

p_city

requires

p_cc

p_state

;

p_state

overrides

p_cc

在WebSocket URL后添加查询参数：

参数	浏览器	说明
`p_cc=US`	Chrome、Firefox	通过两位国家代码路由流量
`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 Handling

CAPTCHA处理

Listen for

oxylabs-captcha-solve-start

oxylabs-captcha-solve-end

, and

oxylabs-captcha-solve-error

window messages.

For CAPTCHAs shown after page load, trigger solving with

window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*')

Supported manual CAPTCHA types:
```
hcaptcha
```
,
```
recaptcha
```
,
```
turnstile
```
.

监听

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
```
。

When to Use

使用场景

Scenario	Use Headless Browser
Complex JavaScript sites	Yes
Anti-bot protected sites	Yes
Browser automation with stealth	Yes
Screenshot/PDF generation	Yes
Simple HTML scraping	Consider Web Scraper API instead

场景	是否使用无头浏览器
复杂JavaScript网站	是
反机器人保护的网站	是
具备隐身能力的浏览器自动化	是
截图/PDF生成	是
简单HTML抓取	建议使用Web Scraper API替代

Supported Libraries

支持的库

Any library supporting Chrome DevTools Protocol (CDP):

Playwright (recommended)
Puppeteer
Selenium with CDP
Custom CDP implementations

Firefox is legacy and should use Playwright

firefox.connect

with supported Playwright versions 1.51 or 1.56.

For more examples, see examples.md.

任何支持Chrome DevTools Protocol (CDP)的库：

Playwright（推荐）
Puppeteer
带CDP的Selenium
自定义CDP实现

Firefox为旧版，应使用Playwright的

firefox.connect

，且仅支持Playwright 1.51或1.56版本。

更多示例请查看examples.md。