CAPTCHA 处理

了解无头浏览器 CAPTCHA 检测和处理机制，以及如何使用它们。

默认情况下，Oxylabs 无头浏览器在页面加载后会自动检测并处理 CAPTCHA。无需进行任何配置或参数设置。

如果目标站点在多步骤交互中动态显示挑战，或者你需要高级事件监控和速度优化，可以使用下文记录的参数、事件和技术。

注意： 访问成功率高度依赖目标站点。结果可能会因目标站点的具体配置、执行级别（例如被动指纹跟踪与主动挑战升级）以及会话住宅 IP 的实时信誉而异。

监控 CAPTCHA 事件

你可以监控求解器的生命周期。内部的 oxylabs-runtime 浏览器扩展会直接将状态事件广播到浏览器的 window 对象。通过注册自定义的 "message" 事件监听器，你的脚本可以跟踪这些事件，从而暂停和恢复操作。

事件类型	描述
oxylabs-captcha-start	求解器已检测到 CAPTCHA 并启动处理流程。
oxylabs-captcha-end	求解器已成功完成并处理了该挑战。
oxylabs-captcha-solve-end	成功后发出的替代完成事件。
oxylabs-captcha-error	求解器未能处理该挑战。

自动求解是 默认启用。如果你追加 solve_captcha=false 到你的连接 URL 中，自动处理将被关闭，且这些事件不会被触发。

代码示例

这些示例展示了如何注入一个 init 脚本，以便在页面导航前捕获运行时 CAPTCHA 事件，从而让你的脚本在正在处理时暂停。

Python（Playwright）

from playwright.sync_api import sync_playwright

username = "USERNAME_abc12"
password = "PASSWORD"
endpoint = "ubc.oxylabs.io"
# 确保 solve_captcha=true 处于启用状态（默认）以触发事件
browser_url = f"wss://{username}:{password}@{endpoint}?solve_captcha=true"

def run():
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(browser_url)
        ctx = browser.contexts[0]
        page = ctx.new_page()

        # 在导航前注入监听器
        ctx.add_init_script("""
            window.addEventListener("message", (event) => {
                if (event.data && event.data.source === "oxylabs-runtime") {
                    window.__extensionStatus = event.data.type;
                }
            });
        """)

        page.goto("https://example.com/captcha-page", wait_until="domcontentloaded")

        # 等待求解器完成（轮询状态标志）
        page.wait_for_function(
            """() => {
                const status = window.__extensionStatus;
                if (status === "oxylabs-captcha-error") {
                    throw new Error("CAPTCHA solving failed");
                }
                return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
            }""",
            timeout=60000
        )
        print("CAPTCHA solved. Resuming automation...")
        browser.close()

if __name__ == "__main__":
    run()

JavaScript（Playwright）

import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?solve_captcha=true`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0];
    const page = await ctx.newPage();

    // 注册 init 脚本以监听 oxylabs-runtime 事件
    await ctx.addInitScript(() => {
        window.addEventListener("message", (e) => {
            if (e.data?.source === "oxylabs-runtime") {
                window.__extensionStatus = e.data.type;
            }
        });
    });

    await page.goto("https://example.com/captcha-page", { waitUntil: "domcontentloaded" });

    try {
        // 暂停脚本执行，直到 CAPTCHA 返回成功求解状态
        await page.waitForFunction(() => {
            const status = window.__extensionStatus;
            if (status === "oxylabs-captcha-error") {
                throw new Error("CAPTCHA solving failed");
            }
            return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
        }, null, { timeout: 60000 });

        console.log("CAPTCHA 已解决。恢复自动化...");
    } catch (err) {
        console.error("绕过执行期间出错：", err.message);
    } finally {
        await browser.close();
    }
})();

JavaScript（Puppeteer）

import puppeteer from "puppeteer";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?solve_captcha=true`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();

    // Puppeteer 替代方案：在文档创建时求值
    await page.evaluateOnNewDocument(() => {
        window.addEventListener("message", (e) => {
            if (e.data?.source === "oxylabs-runtime") {
                window.__extensionStatus = e.data.type;
            }
        });
    });

    await page.goto("https://example.com/captcha-page", { waitUntil: "domcontentloaded" });

    try {
        await page.waitForFunction(() => {
            const status = window.__extensionStatus;
            if (status === "oxylabs-captcha-error") {
                throw new Error("CAPTCHA solving failed");
            }
            return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
        }, { timeout: 60000 });

        console.log("CAPTCHA 已解决。恢复自动化...");
    } catch (err) {
        console.error("绕过执行期间出错：", err.message);
    } finally {
        await browser.close();
    }
})();

动态手动触发

某些目标只会在用户操作后显示 CAPTCHA 挑战（例如，点击交互式表单提交按钮后或执行动态滚动时）。

你可以在会话中的任意时刻，使用无头浏览器的 CAPTCHA 处理器以编程方式触发 window.postMessage 事件直接发送到 window 对象：

window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");

如需了解更多支持的 CAPTCHA 类型，请联系 Oxylabs 支持（在线聊天 或 电子邮件）或你的专属客户经理。

标准触发模式

对于常见元素，在执行用户操作后立即触发求解器：

// 执行表单交互
await page.click("#form-submit-button");

// 为后阶段 CAPTCHA 触发求解
await page.evaluate(() => {
    window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");
});

如需了解更多支持的 CAPTCHA 类型或特定类型的例外情况，请联系 Oxylabs 支持（在线聊天 或 电子邮件）或你的专属客户经理以获取更多详情。

速度优化

处理 CAPTCHA 会增加机械执行延迟。在抓取会强制重复 CAPTCHA 门槛的目标时，可考虑以下方法以获得更好的性能：

重用会话	一旦远程浏览器会话在某个域名上完成 CAPTCHA，验证结果就会被保存。你可以在同一浏览器会话中反复导航或执行更多页面步骤，而无需重新触发挑战求解流程。
多标签页	与其初始化多个独立的 WebSocket 连接（这会启动不同的沙箱并带有空的 Cookie 池），不如在现有会话中打开多个标签页或上下文来并发执行任务。这样可以降低所有页面的连接和验证开销。
自适应禁用	一旦建立可靠的会话信任信号，你就可以通过以下方式连接，完全禁用后台求解器检查 solve_captcha=false。这可绕过进程初始化延迟，适用于你的会话已可直接通过、无需显示挑战的域名。