CAPTCHA 处理

了解 Oxylabs 代理浏览器的 CAPTCHA 检测和处理机制及其使用方式。

默认情况下，Oxylabs Agent Browser 不会 不 自动处理 CAPTCHA。要在页面加载后立即启用自动检测和处理，请添加 solve_captcha=true 到你的连接 URL。

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

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

监控 CAPTCHA 事件

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

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

自动求解是 默认已禁用。附加 solve_captcha=true 到你的连接 URL，即可启用自动处理并开始发出这些事件。

代码示例

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

Python（Playwright）

from playwright.sync_api import sync_playwright

username = "USERNAME_abc12"
password = "PASSWORD"
endpoint = "hb.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 求解失败");
                }
                return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
            }""",
            timeout=60000
        )
        print("CAPTCHA 已解决。继续自动化...")
        browser.close()

if __name__ == "__main__":
    run()

JavaScript（Playwright）

import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "hb.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 求解失败");
            }
            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 = "hb.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 求解失败");
            }
            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 挑战（例如，点击交互式表单提交按钮或执行动态滚动后）。

你可以在会话中的任意时刻通过以下方式以编程方式触发 Agent Browser 的 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 默认关闭，只在需要它的特定连接中启用（solve_captcha=true），而不要在整个工作流中一直开启——这可以避免在不遇到 CAPTCHA 挑战的页面或会话上产生求解器初始化延迟。