Shadow DOM CAPTCHA 处理：访问 Web 组件中的元素 (实用指南)

标准 document.querySelector 无法到达阴影根内部。当 CAPTCHA 小部件在 Web 组件的影子 DOM 内呈现时，您常用的站点密钥提取脚本将返回 null。验证码就在那里 - 您的选择器只是看不到它。

为什么验证码最终出现在 Shadow DOM 中

设想	原因
自定义登录组件	封装为可重用的 Web 组件
第三方表单小部件	小部件供应商将整个表单包装在影子根中
微前端架构	每个微应用都使用独立的 Shadow DOM
设计系统组件	验证码嵌入组件库元素中

检测 Shadow DOM 验证码

在解决之前，请确认验证码位于影子根内：

// In browser DevTools console
// Regular query returns null even though CAPTCHA is visible
document.querySelector('.cf-turnstile');  // null

// Check for shadow hosts
document.querySelectorAll('*').forEach(el => {
  if (el.shadowRoot) {
    const captcha = el.shadowRoot.querySelector('.cf-turnstile, .g-recaptcha');
    if (captcha) {
      console.log('Found CAPTCHA in shadow root of:', el.tagName, el.id || el.className);
      console.log('Sitekey:', captcha.dataset.sitekey);
    }
  }
});

Python：剧作家 Shadow DOM 穿透

Playwright 的 >> 穿透选择器和 locator API 原生处理影子 DOM：

import requests
import time
from playwright.sync_api import sync_playwright

API_KEY = "YOUR_API_KEY"
SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"


def solve_turnstile(sitekey, pageurl):
    """Submit and poll a Turnstile CAPTCHA."""
    resp = requests.post(SUBMIT_URL, data={
        "key": API_KEY,
        "method": "turnstile",
        "sitekey": sitekey,
        "pageurl": pageurl,
        "json": 1,
    }, timeout=30).json()

    if resp.get("status") != 1:
        raise RuntimeError(f"Submit failed: {resp.get('request')}")

    task_id = resp["request"]
    for _ in range(60):
        time.sleep(5)
        poll = requests.get(RESULT_URL, params={
            "key": API_KEY, "action": "get",
            "id": task_id, "json": 1,
        }, timeout=15).json()

        if poll.get("request") == "CAPCHA_NOT_READY":
            continue
        if poll.get("status") == 1:
            return poll["request"]
        raise RuntimeError(f"Solve failed: {poll.get('request')}")

    raise RuntimeError("Timeout")


def extract_from_shadow_dom(page):
    """Extract CAPTCHA sitekey from shadow DOM elements."""

    # Method 1: Playwright's piercing selector (>>)
    # This automatically crosses shadow boundaries
    turnstile = page.locator("css=.cf-turnstile >> visible=true").first
    if turnstile.count() > 0:
        sitekey = turnstile.get_attribute("data-sitekey")
        if sitekey:
            return sitekey

    # Method 2: JavaScript evaluation to pierce all shadow roots
    sitekey = page.evaluate("""
        () => {
            function findInShadowRoots(root) {
                // Check direct children
                const turnstile = root.querySelector('.cf-turnstile');
                if (turnstile && turnstile.dataset.sitekey) {
                    return turnstile.dataset.sitekey;
                }

                const recaptcha = root.querySelector('.g-recaptcha');
                if (recaptcha && recaptcha.dataset.sitekey) {
                    return recaptcha.dataset.sitekey;
                }

                // Recurse into nested shadow roots
                for (const el of root.querySelectorAll('*')) {
                    if (el.shadowRoot) {
                        const found = findInShadowRoots(el.shadowRoot);
                        if (found) return found;
                    }
                }
                return null;
            }
            return findInShadowRoots(document);
        }
    """)

    return sitekey


def inject_token_shadow_dom(page, token, captcha_type="turnstile"):
    """Inject solved token into shadow DOM CAPTCHA element."""
    if captcha_type == "turnstile":
        page.evaluate(f"""
            (token) => {{
                function findAndInject(root) {{
                    // Find the response input inside Turnstile
                    const input = root.querySelector('[name="cf-turnstile-response"]');
                    if (input) {{
                        input.value = token;
                        return true;
                    }}

                    // Recurse into shadow roots
                    for (const el of root.querySelectorAll('*')) {{
                        if (el.shadowRoot && findAndInject(el.shadowRoot)) {{
                            return true;
                        }}
                    }}
                    return false;
                }}
                findAndInject(document);

                // Also try callback if defined
                if (typeof window.turnstileCallback === 'function') {{
                    window.turnstileCallback(token);
                }}
            }}
        """, token)
    elif captcha_type == "recaptcha":
        page.evaluate(f"""
            (token) => {{
                function findAndInject(root) {{
                    const textarea = root.querySelector('#g-recaptcha-response');
                    if (textarea) {{
                        textarea.value = token;
                        textarea.style.display = 'block';
                        return true;
                    }}
                    for (const el of root.querySelectorAll('*')) {{
                        if (el.shadowRoot && findAndInject(el.shadowRoot)) {{
                            return true;
                        }}
                    }}
                    return false;
                }}
                findAndInject(document);

                if (typeof ___grecaptcha_cfg !== 'undefined') {{
                    Object.entries(___grecaptcha_cfg.clients).forEach(([_, client]) => {{
                        Object.entries(client).forEach(([_, val]) => {{
                            if (val && typeof val === 'object') {{
                                Object.entries(val).forEach(([_, v]) => {{
                                    if (v && v.callback) v.callback(token);
                                }});
                            }}
                        }});
                    }});
                }}
            }}
        """, token)


def main():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()
        page.goto("https://staging.example.com/qa-login")
        page.wait_for_load_state("networkidle")

        # Extract sitekey from shadow DOM
        sitekey = extract_from_shadow_dom(page)
        if not sitekey:
            print("No CAPTCHA found in shadow DOM or regular DOM")
            browser.close()
            return

        print(f"Found sitekey: {sitekey}")

        # Solve via CaptchaAI
        token = solve_turnstile(sitekey, page.url)
        print(f"Solved: {token[:40]}...")

        # Inject token back into shadow DOM
        inject_token_shadow_dom(page, token, "turnstile")
        print("Token injected into shadow DOM")

        # Submit the form
        page.click("button[type='submit']")
        page.wait_for_load_state("networkidle")

        browser.close()


main()

JavaScript：Puppeteer Shadow DOM 遍历

const puppeteer = require("puppeteer");

const API_KEY = "YOUR_API_KEY";
const SUBMIT_URL = "https://ocr.captchaai.com/in.php";
const RESULT_URL = "https://ocr.captchaai.com/res.php";

async function solveTurnstile(sitekey, pageurl) {
  const params = new URLSearchParams({
    key: API_KEY, method: "turnstile", sitekey, pageurl, json: "1",
  });
  const resp = await (await fetch(SUBMIT_URL, { method: "POST", body: params })).json();
  if (resp.status !== 1) throw new Error(`Submit: ${resp.request}`);

  const taskId = resp.request;
  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const url = `${RESULT_URL}?key=${API_KEY}&action=get&id=${taskId}&json=1`;
    const poll = await (await fetch(url)).json();
    if (poll.request === "CAPCHA_NOT_READY") continue;
    if (poll.status === 1) return poll.request;
    throw new Error(`Solve: ${poll.request}`);
  }
  throw new Error("Timeout");
}

async function extractSitekeyFromShadowDOM(page) {
  return page.evaluate(() => {
    function searchShadowRoots(root) {
      const selectors = [".cf-turnstile", ".g-recaptcha", ".h-captcha"];
      for (const sel of selectors) {
        const el = root.querySelector(sel);
        if (el && el.dataset.sitekey) return el.dataset.sitekey;
      }
      for (const el of root.querySelectorAll("*")) {
        if (el.shadowRoot) {
          const found = searchShadowRoots(el.shadowRoot);
          if (found) return found;
        }
      }
      return null;
    }
    return searchShadowRoots(document);
  });
}

async function injectTokenShadowDOM(page, token) {
  await page.evaluate((t) => {
    function inject(root) {
      const input = root.querySelector('[name="cf-turnstile-response"]');
      if (input) { input.value = t; return true; }
      const textarea = root.querySelector("#g-recaptcha-response");
      if (textarea) { textarea.value = t; return true; }
      for (const el of root.querySelectorAll("*")) {
        if (el.shadowRoot && inject(el.shadowRoot)) return true;
      }
      return false;
    }
    inject(document);
  }, token);
}

(async () => {
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto("https://staging.example.com/qa-login", { waitUntil: "networkidle2" });

  const sitekey = await extractSitekeyFromShadowDOM(page);
  if (!sitekey) {
    console.log("No CAPTCHA found in shadow DOM");
    await browser.close();
    return;
  }

  console.log(`Sitekey: ${sitekey}`);
  const token = await solveTurnstile(sitekey, page.url());
  console.log(`Solved: ${token.substring(0, 40)}...`);

  await injectTokenShadowDOM(page, token);
  await page.click('button[type="submit"]');
  await page.waitForNavigation();

  await browser.close();
})();

Shadow DOM 深度注意事项

深度	例子	方法
1级	`<custom-form> #shadow-root > .cf-turnstile`	直接影子根查询
2 个以上级别	`<app-shell> #shadow > <login-form> #shadow > .cf-turnstile`	递归遍历
打开影子根	`el.shadowRoot` 可访问	标准方法——使用递归
封闭的影子根	`el.shadowRoot` 返回 null	无法刺穿；使用 `page.evaluate` 和 `attachShadow({mode:'open'})` 覆盖或拦截渲染

后备诊断顺序

首先检查打开的影子根，然后检查 iframe 边界，最后检查应用程序级回调或注入的钩子。
记录哪一层暴露了挑战，以便更容易发现未来的目标变化。
保留封闭根的最后手段，而不是假设每个页面都统一公开 DOM 访问。

故障排除

问题	原因	处理方式
`shadowRoot` 返回 `null`	封闭的影子 DOM	在页面加载之前覆盖 `attachShadow` 以强制 `mode: 'open'`
找到 Sitekey 但令牌被拒绝	错误的 pageurl 发送到求解器	在提取时使用 `page.url()`，而不是硬编码 URL
令牌已注入但表单未提交	验证码回调未触发	设置token值后查找并调用回调函数
递归搜索速度很慢	深度 DOM 树	限制递归深度；目标已知影子主机标签名称
初始加载时未找到验证码	小部件异步加载	首先等待影子宿主元素：`page.waitForSelector('custom-form')`

常问问题

我如何知道验证码是否使用 Shadow DOM？

在 Chrome DevTools 中，检查 CAPTCHA 元素。如果您在验证码标记上方看到 #shadow-root (open) 或 #shadow-root (closed)，则它位于影子根内。 document 中的常规 querySelector 找不到它。

我可以完全避免影子 DOM 遍历吗？

如果您直接使用 CaptchaAI API（不是浏览器注入），则只需要 sitekey 和 pageurl - Shadow DOM 并不重要。仅当您必须从实时页面提取 sitekey 或将token 提交回 DOM 时，才需要 Shadow DOM 处理。

封闭的影子根怎么样？

封闭的影子根阻止 el.shadowRoot 访问。解决方法是在页面加载之前覆盖 Element.prototype.attachShadow，强制所有影子根进入打开模式。这适用于 page.evaluateOnNewDocument 的 Playwright 和 Puppeteer。

下一步

处理隐藏在 Web 组件内的验证码 –”获取您的 CaptchaAI API 密钥并实现shadow DOM遍历。

相关指南：

Shadow DOM CAPTCHA 处理：访问 Web 组件中的元素

为什么验证码最终出现在 Shadow DOM 中

检测 Shadow DOM 验证码

Python：剧作家 Shadow DOM 穿透

JavaScript：Puppeteer Shadow DOM 遍历

Shadow DOM 深度注意事项

后备诊断顺序

故障排除

常问问题

我如何知道验证码是否使用 Shadow DOM？

我可以完全避免影子 DOM 遍历吗？

封闭的影子根怎么样？

相关文章

下一步

使用 CaptchaAI 构建客户端验证码管道

弹出模式中的验证码：检测和token 提交

高需求 e-commerce checkout 的 CAPTCHA 测试

使用 CaptchaAI 进行 QA 浏览器配置文件隔离

Cloudflare Turnstile 令牌到期时间和竞争条件

在自有 QA 中安全地缓存与复用 CAPTCHA token