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

博客

博客

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

Ethan Collins

Pattern Recognition Specialist

26-Mar-2026

AI浏览器代理正在重塑开发者与网络的交互方式。从数据抓取到自动化工作流，这些代理可以导航页面、填写表单并提取信息，而无需人工干预。但当出现CAPTCHA时，代理会停滞。

HyperBrowser 提供了专为AI代理设计的基于云的浏览器基础设施，原生支持Turnstile和reCAPTCHA的CAPTCHA解决。但网络上还有超过两种CAPTCHA类型。AWS WAF、GeeTest、企业级reCAPTCHA变体以及其他反机器人挑战仍需原生工具之外的解决方案。

CapSolver 填补了这一空白。通过将CapSolver Chrome扩展直接上传到HyperBrowser的扩展API，您可以在每个会话、每种CAPTCHA类型和每个规模上获得全面的CAPTCHA覆盖，而无需更改自动化代码。

什么是HyperBrowser？

HyperBrowser 是一个专为AI代理设计的云浏览器基础设施平台。它提供开箱即用的托管浏览器会话，支持原生Chrome DevTools Protocol (CDP) 访问、代理支持和反检测功能。

核心功能

云浏览器会话：按需启动隔离的浏览器实例，无需本地安装Chrome
原生CDP访问：通过WebSocket直接连接Playwright、Puppeteer或Selenium到云会话
HyperAgent：内置AI浏览器自动化代理，用于自然语言网络任务
反检测：每个会话内置隐身配置文件、住宅代理和指纹随机化
Chrome扩展支持：一流的扩展上传API——将扩展打包为ZIP，上传并附加到任何会话
可扩展基础设施：无需管理浏览器池即可运行数百个并发会话

开发者为何选择HyperBrowser

HyperBrowser消除了浏览器自动化的运营负担。您无需管理Chromium二进制文件、无头配置、代理轮换和反指纹技术，而是获得一个干净的API，返回WebSocket URL。连接您的Playwright或Puppeteer脚本并开始自动化。

什么是CapSolver？

CapSolver 是一个领先的CAPTCHA解决服务，提供AI驱动的解决方案来绕过各种CAPTCHA挑战。凭借对多种CAPTCHA类型的支持和快速响应时间，CapSolver可以无缝集成到自动化工作流中。

支持的CAPTCHA类型

前提条件

在设置集成之前，请确保您已满足以下条件：

HyperBrowser账户，带有API密钥(在hyperbrowser.ai注册)
CapSolver账户，带有API密钥和积分(在此注册)
已下载并配置的CapSolver Chrome扩展
Node.js 18+，并安装了@hyperbrowser/sdk和playwright-core

bash 复制代码

npm install @hyperbrowser/sdk playwright-core

分步设置

步骤1：获取您的CapSolver API密钥

在capsolver.com注册或登录
导航到您的仪表板
复制您的API密钥（格式：CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX）
为您的账户添加积分（使用优惠码HYPERBROWSER在首次充值时额外获得6%）

步骤2：下载并配置CapSolver扩展

下载CapSolver Chrome扩展并用您的API密钥进行配置：

转到CapSolver扩展的GitHub发布页面
下载最新的CapSolver.Browser.Extension-chrome-vX.X.X.zip
解压扩展：

bash 复制代码

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

打开capsolver-extension/assets/config.js并设置您的API密钥：

js 复制代码

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

验证扩展结构：

bash 复制代码

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

步骤3：压缩扩展目录

HyperBrowser的扩展上传API需要一个ZIP文件。打包配置好的扩展：

bash 复制代码

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

这会在项目根目录中创建capsolver-extension.zip，准备上传。

步骤4：将扩展上传到HyperBrowser

使用HyperBrowser SDK上传扩展。这只需要执行一次——返回的extensionId可在所有会话中重复使用。

typescript 复制代码

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——您将在每个会话中重复使用它

提示：将ext.id存储在环境变量或配置中。如果您更改了扩展版本或API密钥，只需重新上传即可。

步骤5：创建带有扩展的会话

创建一个加载CapSolver扩展的HyperBrowser会话：

typescript 复制代码

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);

注意：使用CapSolver时，设置solveCaptchas: false以避免两种解决机制之间的冲突。如果您希望两者作为备用链，参见下面的“何时使用原生与CapSolver”部分。

步骤6：将Playwright连接到会话

通过WebSocket端点将Playwright连接到HyperBrowser会话：

typescript 复制代码

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);

步骤7：在reCAPTCHA演示页面上测试

这是一个完整的端到端脚本，上传扩展、创建会话、解决CAPTCHA并验证结果：

typescript 复制代码

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);

运行它：

bash 复制代码

HYPERBROWSER_API_KEY=your_key npx tsx captcha-test.ts

其工作原理

以下是扩展上传到CAPTCHA解决的完整流程：

复制代码

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

  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 Chrome扩展方法相比基于API的解决方法有一个关键优势：扩展在浏览器上下文中运行。这意味着：

自动检测：内容脚本扫描每页上的已知CAPTCHA小部件——无需手动检测代码
原生令牌注入：令牌直接注入到DOM中，就像真实用户的浏览器一样
无需协调代码：您不需要编写createTask() / getTaskResult() / 注入逻辑——所有操作由扩展处理
适用于任何框架：无论您使用Playwright、Puppeteer还是Selenium连接，扩展的工作方式都相同

在以下情况下使用CapSolver扩展：

您遇到AWS WAF、GeeTest或企业级reCAPTCHA变体
您需要更快的解决时间用于高吞吐量自动化
您希望在HyperBrowser和自托管浏览器上保持一致的CAPTCHA解决
您需要最广泛的CAPTCHA覆盖以应对未知目标站点

typescript 复制代码

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

作为备用链同时使用：

为了最大可靠性，您可以启用两者。原生解决处理Turnstile/reCAPTCHA且无需额外成本，而CapSolver处理其他所有内容：

typescript 复制代码

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

注意：当两者同时启用时（例如reCAPTCHA），先解决的获胜。实际上这没有问题——没有冲突。

替代方案：CapSolver API方法

如果您不想使用浏览器扩展——或需要对解决流程有更精细的控制——您可以直接使用CapSolver REST API。这适用于任何HyperBrowser会话，无需上传扩展。

工作原理

导航到带有CAPTCHA的页面
从DOM中检测CAPTCHA类型和站点密钥
在CapSolver API上调用createTask
轮询getTaskResult直到令牌就绪
通过Playwright将令牌注入页面
提交表单

完整示例

typescript 复制代码

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);

何时使用API与扩展程序

	扩展程序	API
设置	上传ZIP一次，重复使用ID	无需设置——只需API密钥
检测	自动（内容脚本）	手动（查询DOM获取sitekey）
令牌注入	自动	手动（评估JS）
控制	不透明——扩展程序处理所有内容	对每个步骤有完全控制
最适合	设置并忘记的自动化	自定义解决逻辑，重试策略

故障排除

扩展程序未在会话中加载

症状: CAPTCHA未被解决；页面表现得好像没有扩展程序。

可能原因:

错误的扩展ID -- 验证从client.extensions.create()返回的ID是否正确传递
损坏的ZIP -- 重新压缩扩展目录（确保manifest.json位于ZIP的根目录，而不是子文件夹中）
缺少API密钥 -- 在压缩前检查assets/config.js是否有有效的CapSolver API密钥

修复:

bash 复制代码

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

CAPTCHA未被解决（表单失败）

症状: 页面加载，但等待后CAPTCHA仍未被解决。

可能原因:

等待时间不足 -- 将waitForTimeout增加到45-60秒
无效的API密钥 -- 登录到你的CapSolver仪表板并验证密钥
余额不足 -- 为你的CapSolver账户充值
不支持的CAPTCHA类型 -- 查看CapSolver文档以获取支持的类型

会话WebSocket连接失败

症状: chromium.connectOverCDP()抛出连接错误。

修复: 确保会话仍处于活动状态。会话有超时时间（默认因计划而异）。如果之前的会话已过期，请创建新会话：

typescript 复制代码

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);
}

扩展程序在本地有效但在HyperBrowser中无效

症状: CapSolver扩展在本地Chrome中有效，但在HyperBrowser会话中失败。

可能原因:

config.js未包含在ZIP中 -- 双重检查ZIP是否包含修改后的assets/config.js
网络限制 -- 扩展需要访问api.capsolver.com。确保HyperBrowser会话的网络允许出站HTTPS
扩展版本不匹配 -- 使用最新的CapSolver扩展版本以获得最佳兼容性

最佳实践

1. 上传扩展一次，重复使用ID

扩展上传是一次性操作。存储返回的extensionId并在所有会话中重复使用：

typescript 复制代码

// 上传一次
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);
}

2. 始终启用代理

CAPTCHAs在来自数据中心IP的请求中更可能出现（且更难解决）。HyperBrowser的内置代理有助于：

typescript 复制代码

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

3. 使用适当的等待时间

不同类型的CAPTCHA需要不同的解决时间：

CAPTCHA类型	典型解决时间	推荐等待时间
reCAPTCHA v2（复选框）	5-15秒	30秒
reCAPTCHA v2（不可见）	5-15秒	25秒
reCAPTCHA v3	3-10秒	20秒
Cloudflare Turnstile	3-10秒	20秒
AWS WAF	5-15秒	30秒
GeeTest v3/v4	5-20秒	30秒

提示: 如果不确定，使用30秒。等待更长时间比过早提交更好。

4. 监控你的CapSolver余额

每次CAPTCHA解决都会消耗积分。在自动化中添加余额检查以避免中断：

typescript 复制代码

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充值");
}

5. 清理会话

完成时始终停止会话以避免不必要的费用：

typescript 复制代码

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

6. 更改API密钥后重新压缩

如果轮换你的CapSolver API密钥，需要更新config.js，重新压缩并重新上传：

bash 复制代码

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

然后上传新ZIP并更新存储的extensionId。

结论

HyperBrowser和CapSolver共同提供了AI浏览器自动化中最全面的CAPTCHA解决设置：

HyperBrowser处理基础设施——云会话、代理、反检测和原生Turnstile/reCAPTCHA解决
CapSolver扩展覆盖范围——AWS WAF、GeeTest、企业reCAPTCHA以及原生解决器无法覆盖的每种CAPTCHA类型

集成简单：将CapSolver扩展压缩，通过HyperBrowser SDK上传一次，然后将其附加到任何会话。无需代码级CAPTCHA检测，无需令牌注入，无需API轮询。扩展在浏览器上下文中处理所有内容。

无论你是构建网络爬虫、AI代理还是自动化测试管道，这种组合意味着CAPTCHAs不再是障碍——无论类型如何。

准备好开始了吗？ 在CapSolver注册并使用优惠码 HYPERBROWSER 在首次充值时获得额外6%的奖励！

常见问题

什么是HyperBrowser？

HyperBrowser是一个AI代理的云浏览器基础设施平台。它提供托管的、隔离的浏览器会话，具有原生CDP访问权限，因此你可以将Playwright、Puppeteer或Selenium连接到云托管的Chromium实例。它包括内置代理、反检测和原生Turnstile/reCAPTCHA解决。

扩展上传是如何工作的？

HyperBrowser有一个一流的扩展API。你将Chrome扩展目录压缩为ZIP，通过client.extensions.create()上传，并收到一个extensionId。将该ID传递给client.sessions.create()，扩展将自动加载到云浏览器会话中。

CapSolver支持哪些CAPTCHA类型？

CapSolver支持reCAPTCHA v2（复选框和不可见）、reCAPTCHA v3、reCAPTCHA企业、Cloudflare Turnstile、Cloudflare 5秒挑战、AWS WAF、GeeTest v3/v4等。Chrome扩展会自动检测CAPTCHA类型并解决。

CapSolver的费用是多少？

CapSolver提供基于CAPTCHA类型和数量的有竞争力的价格。访问capsolver.com查看当前价格。使用代码 HYPERBROWSER 在首次充值时获得6%的奖励。

我需要为每个会话重新上传扩展吗？

不需要。上传扩展一次并重复使用返回的extensionId在所有会话中。只有在更改扩展内的CapSolver API密钥或更新扩展版本时才需要重新上传。

我可以使用Puppeteer而不是Playwright吗？

可以。HyperBrowser支持Playwright、Puppeteer和Selenium。将Playwright的connectOverCDP调用替换为Puppeteer的等效项：

typescript 复制代码

import puppeteer from "puppeteer-core";

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

无论你使用哪种自动化框架，CapSolver扩展都会以相同的方式工作。

HyperBrowser是免费的吗？

HyperBrowser提供一个免费计划，有有限的会话数量。付费计划解锁更多会话、更长的超时时间和其他功能。访问hyperbrowser.ai查看当前价格。

合规声明：本博客提供的信息仅供参考。CapSolver 致力于遵守所有适用的法律和法规。严禁以非法、欺诈或滥用活动使用 CapSolver 网络，任何此类行为将受到调查。我们的验证码解决方案在确保 100% 合规的同时，帮助解决公共数据爬取过程中的验证码难题。我们鼓励负责任地使用我们的服务。如需更多信息，请访问我们的服务条款和隐私政策。