如何在HyperBrowser中使用CapSolver解决任何CAPTCHA（完整设置指南）

npm install @hyperbrowser/sdk playwright-core

mkdir -p capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d capsolver-extension/

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  // 在此处输入您的密钥
  useCapsolver: true,
  // ...其余配置
};

ls capsolver-extension/manifest.json
# 应存在

cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..

import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

// 上传CapSolver扩展（一次性操作）
const ext = await client.extensions.create({
  filePath: "capsolver-extension.zip",
});

console.log("扩展ID:", ext.id);
// 保存此ID——您将在每个会话中重复使用它

const session = await client.sessions.create({
  extensionIds: [ext.id],
  useProxy: true, // 需要付费计划——免费版可省略
  solveCaptchas: false, // 使用CapSolver而非原生解决
});

console.log("会话ID:", session.id);
console.log("WebSocket URL:", session.wsEndpoint);

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

// 导航到CAPTCHA保护的页面
await page.goto("https://www.google.com/recaptcha/api2/demo");

// 等待CapSolver扩展检测并解决CAPTCHA
await page.waitForTimeout(30000);

// 提交表单
await page.click("#recaptcha-demo-submit");
await page.waitForLoadState("networkidle");

// 验证成功
const result = await page.textContent("body");
console.log("结果:", result);
// 预期：包含“Verification Success”

await browser.close();
await client.sessions.stop(session.id);

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";

const HYPERBROWSER_API_KEY = process.env.HYPERBROWSER_API_KEY!;
const CAPSOLVER_EXTENSION_ID = process.env.CAPSOLVER_EXTENSION_ID; // 可选：复用现有ID

async function main() {
  const client = new Hyperbrowser({ apiKey: HYPERBROWSER_API_KEY });

  // 步骤1：上传扩展（或复用现有ID）
  let extensionId = CAPSOLVER_EXTENSION_ID;

  if (!extensionId) {
    const ext = await client.extensions.create({
      filePath: "capsolver-extension.zip",
    });
    extensionId = ext.id;
    console.log("上传扩展:", extensionId);
  }

  // 步骤2：创建带有CapSolver扩展的会话
  const session = await client.sessions.create({
    extensionIds: [extensionId],
    useProxy: true, // 需要付费计划——免费版可省略
    solveCaptchas: false,
  });

  console.log("会话已启动:", session.id);

  // 步骤3：连接Playwright
  const browser = await chromium.connectOverCDP(session.wsEndpoint);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  try {
    // 步骤4：导航到reCAPTCHA演示
    console.log("导航到reCAPTCHA演示...");
    await page.goto("https://www.google.com/recaptcha/api2/demo");

    // 步骤5：等待CapSolver解决CAPTCHA
    console.log("等待CapSolver解决CAPTCHA...");
    await page.waitForTimeout(30000);

    // 步骤6：提交表单
    console.log("提交表单...");
    await page.click("#recaptcha-demo-submit");
    await page.waitForLoadState("networkidle");

    // 步骤7：检查结果
    const bodyText = await page.textContent("body");

    if (bodyText?.includes("Verification Success")) {
      console.log("CAPTCHA成功解决！");
    } else {
      console.log("验证结果:", bodyText?.slice(0, 200));
    }
  } finally {
    await browser.close();
    await client.sessions.stop(session.id);
    console.log("会话已停止。");
  }
}

main().catch(console.error);

HYPERBROWSER_API_KEY=your_key npx tsx captcha-test.ts

  一次性设置
  ═══════════════════════════════════════════════════════

  capsolver-extension/           HyperBrowser云
  ├── manifest.json    ──ZIP──►  POST /extensions
  ├── assets/config.js           │
  └── background.js              ▼
                                 extensionId: "ext_abc123"
                                 (存储并可重复使用)

  每次会话流程
  ═══════════════════════════════════════════════════════

  您的脚本                    HyperBrowser云
  ─────────────────────────────────────────────────────
  sessions.create({       ──►    启动云Chromium
    extensionIds: [id],          │
    useProxy: true               ├── 加载CapSolver扩展
  })                             ├── 应用代理+隐身
                                 ▼
                          ◄──    wsEndpoint (WebSocket URL)

  playwright.connectOverCDP()    连接到云浏览器
       │
       ▼
  page.goto(target_url)   ──►   Chromium加载页面
                                 ┌─────────────────────────────┐
                                 │  页面上的CAPTCHA小部件    │
                                 │                              │
                                 │  CapSolver扩展：        │
                                 │  1. 内容脚本检测页面上的CAPTCHA类型 │
                                 │  2. 服务工作者调用CapSolver API            │
                                 │  3. 接收解决方案令牌             │
                                 │  4. 将令牌注入到隐藏表单字段中        │
                                 └─────────────────────────────┘
                                      │
  page.waitForTimeout(30s)            │ (在此处解决)
       │                              │
       ▼                              ▼
  page.click("Submit")    ──►   表单提交，带有有效令牌
                                      │
                          ◄──         ▼
                                 Google演示：“Verification Success!”

// 全面覆盖：CapSolver扩展
const session = await client.sessions.create({
  extensionIds: [capsolverExtId],
  solveCaptchas: false,
  useProxy: true, // 需要付费计划——免费版可省略
});

// 双重保障：两者均启用
const session = await client.sessions.create({
  extensionIds: [capsolverExtId],
  solveCaptchas: true, // 原生处理Turnstile/reCAPTCHA
  useProxy: true, // 需要付费计划——免费版可省略
  // CapSolver扩展处理AWS WAF、GeeTest等
});

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
const HYPERBROWSER_API_KEY = process.env.HYPERBROWSER_API_KEY!;
const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY!;

async function solveCaptchaViaAPI(
  pageUrl: string,
  siteKey: string
): Promise<string> {
  // 创建任务
  const createRes = await fetch("https://api.capsolver.com/createTask", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      clientKey: CAPSOLVER_API_KEY,
      task: {
        type: "ReCaptchaV2TaskProxyLess",
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const { taskId, errorDescription } = await createRes.json();
  if (!taskId) throw new Error(`createTask failed: ${errorDescription}`);

  // 轮询结果
  for (let i = 0; i < 40; i++) {
    await new Promise((r) => setTimeout(r, 3000));
    const resultRes = await fetch("https://api.capsolver.com/getTaskResult", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientKey: CAPSOLVER_API_KEY, taskId }),
    });
    const result = await resultRes.json();
    if (result.status === "ready") {
      return result.solution.gRecaptchaResponse;
    }
  }
  throw new Error("Solve timeout");
}

async function main() {
  const client = new Hyperbrowser({ apiKey: HYPERBROWSER_API_KEY });

  // 不需要扩展程序——只需一个普通会话
  const session = await client.sessions.create({
    solveCaptchas: false,
  });

  const browser = await chromium.connectOverCDP(session.wsEndpoint);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  try {
    await page.goto("https://www.google.com/recaptcha/api2/demo");

    // 从DOM中检测sitekey
    const siteKey = await page.evaluate(() => {
      const el = document.querySelector(".g-recaptcha[data-sitekey]");
      return el?.getAttribute("data-sitekey") ?? "";
    });
    console.log("Sitekey:", siteKey);

    // 通过CapSolver API解决
    const token = await solveCaptchaViaAPI(page.url(), siteKey);
    console.log("收到令牌，长度:", token.length);

    // 注入令牌
    await page.evaluate((t) => {
      const textarea = document.querySelector(
        'textarea[name="g-recaptcha-response"]'
      );
      if (textarea) (textarea as HTMLTextAreaElement).value = t;
    }, token);

    // 提交
    await page.click("#recaptcha-demo-submit");
    await page.waitForLoadState("networkidle");

    const body = await page.textContent("body");
    console.log(
      body?.includes("Verification Success")
        ? "通过API解决CAPTCHA！"
        : body?.slice(0, 200)
    );
  } finally {
    await browser.close();
    await client.sessions.stop(session.id);
  }
}

main().catch(console.error);

# 验证ZIP结构 -- manifest.json应位于根目录
unzip -l capsolver-extension.zip | head -20
# 应显示: manifest.json (NOT capsolver-extension/manifest.json)

try {
  const browser = await chromium.connectOverCDP(session.wsEndpoint);
} catch (err) {
  console.log("会话已过期，创建新会话...");
  const newSession = await client.sessions.create({
    extensionIds: [extensionId],
    useProxy: true, // 需要付费计划 —— 免费版请省略
  });
  const browser = await chromium.connectOverCDP(newSession.wsEndpoint);
}

// 上传一次
const ext = await client.extensions.create({ filePath: "capsolver-extension.zip" });
const CAPSOLVER_EXT_ID = ext.id;

// 在每个会话中重复使用
for (const url of targetUrls) {
  const session = await client.sessions.create({
    extensionIds: [CAPSOLVER_EXT_ID],
    useProxy: true, // 需要付费计划 —— 免费版请省略。住宅代理可减少CAPTCHA频率
  });
  // ... 自动化
  await client.sessions.stop(session.id);
}

const session = await client.sessions.create({
  extensionIds: [extensionId],
  useProxy: true, // 需要付费计划 —— 免费版请省略。住宅代理可减少CAPTCHA频率
});

import axios from "axios";

async function checkBalance(apiKey: string): Promise<number> {
  const response = await axios.post("https://api.capsolver.com/getBalance", {
    clientKey: apiKey,
  });
  return response.data.balance || 0;
}

const balance = await checkBalance(process.env.CAPSOLVER_API_KEY!);
if (balance < 1) {
  console.warn("CapSolver余额不足！请访问capsolver.com充值");
}

try {
  // ... 你的自动化代码
} finally {
  await browser.close();
  await client.sessions.stop(session.id);
}

# 在config.js中更新密钥后：
cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.wsEndpoint,
});