> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/headless-browser/captcha-chu-li.md).

# CAPTCHA 处理

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

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

{% hint style="info" %}
**注意：** 访问成功率高度依赖目标站点。结果可能因目标站点的具体配置、执行强度（例如，被动指纹跟踪 vs. 主动挑战升级）以及会话住宅 IP 的实时信誉而异。
{% endhint %}

## 监控 CAPTCHA 事件

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

<table><thead><tr><th width="243">事件类型</th><th>描述</th></tr></thead><tbody><tr><td><code>oxylabs-captcha-start</code></td><td>求解器已检测到 CAPTCHA，并开始处理流程。</td></tr><tr><td><code>oxylabs-captcha-end</code></td><td>求解器已成功完成并处理了该挑战。</td></tr><tr><td><code>oxylabs-captcha-solve-end</code></td><td>成功后发出的备用完成事件。</td></tr><tr><td><code>oxylabs-captcha-error</code></td><td>求解器未能处理该挑战。</td></tr></tbody></table>

{% hint style="info" %}
自动求解 **默认已启用**。如果你在 `solve_captcha=false` 添加到连接 URL 中，则会关闭自动处理，并且不会发出这些事件。
{% endhint %}

### 代码示例

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

{% tabs %}
{% tab title="Python（Playwright）" %}

```python
from playwright.sync_api import sync_playwright

username = "USERNAME_abc12"
password = "PASSWORD"
endpoint = "ubc.oxylabs.io"
# Ensure solve_captcha=true is active (default) to emit events
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()
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
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();

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

{% endtab %}

{% tab title="JavaScript (Puppeteer)" %}

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

{% endtab %}
{% endtabs %}

## 动态手动触发

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

你可以在会话中的任何时刻使用无头浏览器的 CAPTCHA 处理器程序化触发 `window.postMessage` 事件直接到 window 对象：

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

{% hint style="info" %}
要了解支持的 CAPTCHA 类型，请联系 Oxylabs 支持（[在线聊天](https://oxylabs.io/) 或 [电子邮件](mailto:support@oxylabs.io)）或你的专属客户经理。
{% endhint %}

### 标准触发模式

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

```javascript
// Perform form interaction
await page.click("#form-submit-button");

// Trigger solving for late-stage CAPTCHA
await page.evaluate(() => {
    window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");
});
```

{% hint style="info" %}
要了解支持的 CAPTCHA 类型或特定类型的例外情况，请联系 Oxylabs 支持（[在线聊天](https://oxylabs.io/) 或 [电子邮件](mailto:support@oxylabs.io)）或你的专属客户经理，以了解更多详情。
{% endhint %}

## 速度优化

处理 CAPTCHA 会增加机械执行延迟。对于强制重复 CAPTCHA 门禁的目标站点，可考虑以下方法以提升性能：

<table data-header-hidden><thead><tr><th width="175"></th><th></th></tr></thead><tbody><tr><td><strong>复用会话</strong></td><td>当远程浏览器会话在某个域名上完成 CAPTCHA 后，验证结果会被保存。你可以在同一浏览器会话中重复导航或执行额外页面步骤，而无需重新触发挑战求解流程。</td></tr><tr><td><strong>多标签页</strong> </td><td>不要使用单独的 WebSocket 连接（这会启动具有空 Cookie 池的独立沙箱），而应在现有会话中打开多个标签页或上下文来并发执行任务，从而减少所有页面的连接和验证时间。</td></tr><tr><td><strong>自适应禁用</strong></td><td>一旦建立了可靠的会话信任信号，就使用 <code>solve_captcha=false</code>禁用后台求解器检查，以避免在你的会话已可自由通过的域名上产生进程初始化延迟。</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/cn/headless-browser/captcha-chu-li.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.