CAPTCHA 处理

了解无头浏览器 CAPTCHA 检测和处理机制及其使用方法。

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

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

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

监控 CAPTCHA 事件

你可以监控求解器的生命周期。内部的 oxylabs-runtime 浏览器扩展会直接向浏览器的 window object. By registering a custom "message" event listener, your script can trace these events to pause and resume actions.

事件类型	说明
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 enables handling and event emission (off by default)
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()

        # Inject listener BEFORE navigation
        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")

        # Wait for solver to complete (polls status flag)
        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 = "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();

    // Register init script to listen for oxylabs-runtime events
    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 {
        // Halt script execution until CAPTCHA returns positive solve status
        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 solved. Resuming automation...");
    } catch (err) {
        console.error("Error during bypass execution:", 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 alternative: Evaluate on document creation
    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 solved. Resuming automation...");
    } catch (err) {
        console.error("Error during bypass execution:", err.message);
    } finally {
        await browser.close();
    }
})();

动态手动触发

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

你可以在会话中的任何时刻通过 window.postMessage 事件直接向 window 对象触发无头浏览器的 CAPTCHA 处理器：

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 挑战的页面或会话上产生求解器初始化延迟。