如何将 Lightpanda 爬虫连接到 CAPTCHA 解决器 API

摘要

• Lightpanda 提供无头浏览器；单独的 CAPTCHA 接口在授权流程中为受支持的挑战返回结果。
• 通过 Puppeteer 连接 Lightpanda 的 CDP 端点，并在构造求解请求前检查真实页面。
• 对于 reCAPTCHA v2，使用当前页面 URL、公开站点密钥以及该挑战文档中要求的其他参数。
• 在求解器运行期间保持原始页面打开。响应令牌必须送达正确应用的回调或提交流程。
• 浏览器连接测试并不能证明 CAPTCHA 脚本兼容性或最终网站会接受结果。需在你被允许的测试页面上单独验证。

Lightpanda 是为自动化、爬虫、测试和浏览器代理构建的无头浏览器。开发者通过诸如 Chrome DevTools Protocol 等接口来控制它，通常配合 Puppeteer 使用。它可以执行页面 JavaScript 并检查 DOM，这在仅靠 HTTP 响应无法提供工作流所需信息时非常有用。

CAPTCHA 是单独的一步。通过 Lightpanda 加载页面并不代表已完成其验证码挑战。CapSolver 可以为受支持的 CAPTCHA 提供有文档的求解 API，而你的应用则仍然负责页面状态和最终结果。

本指南将这些职责串联起来，而不假设每个 CAPTCHA 页面都像 Chromium 那样表现。可运行示例用于验证浏览器连接。求解器请求和应用端接受则需要你自己的凭据和一个授权挑战。

理解两条连接

Lightpanda 的 CAPTCHA 集成需要两条连接：一条连接浏览器，另一条从应用后端连接到求解器 API。

Lightpanda 仓库展示了 Puppeteer 如何连接到 CDP 端点。浏览器导航、页面检查以及应用回调都在该侧工作流中完成。CapSolver 任务 API 接收与任务相关的输入，并返回任务响应。

不要将求解器 API 请求指向 CDP 端口。也不要把浏览器 WebSocket URL 作为 websiteURL 发送。一个地址是控制浏览器进程，另一个地址则标识加载 CAPTCHA 的网页。

API 合同也划定了集成所能了解的信息边界。求解结果并不是能自动恢复所有浏览器的命令。应用必须按其页面的预期方式使用返回的字段。

安装并启动浏览器

在隔离的项目文件夹中安装 Lightpanda 和 Puppeteer，再添加付费求解请求。

连接示例使用 Lightpanda 1.0.2、Puppeteer Core 25.16.0 和 Node.js 24。使用 npm install --save-exact puppeteer-core@25.16.0 安装 Node 依赖。从官方 1.0.2 发布页下载适用于你操作系统和处理器的二进制文件，赋予其可执行权限，并用 ./lightpanda version 确认版本。

使用 ./lightpanda serve --host 127.0.0.1 --port 9227 启动本地 CDP 服务端。在客户端连接期间保持该终端运行。下面示例中的端口必须与服务端端口一致。开发环境下使用本地绑定。

在继续之前准备一个被允许的测试页面。初始连接检查可以使用你自有的简单页面；之后的 CAPTCHA 测试则需要一个带真实挑战的页面，并在应用侧有办法观察其被接受情况。同时准备一个有效的 CapSolver API 密钥和余额，以便创建付费求解任务。

本指南不演示任何付费求解。已验证的浏览器步骤和 API 认证响应只建立各自的连接面；它们并不能证明 CAPTCHA 求解成功，或与特定外部网站兼容。

验证 Puppeteer 与 Lightpanda 的连接

将 AUTHORIZED_TEST_URL 设为你的测试页面，把以下内容保存为 lightpanda-connect.mjs，然后运行 node lightpanda-connect.mjs。

该示例改写自 Lightpanda 官方的 Puppeteer 连接模式。它创建一个浏览器上下文，加载被允许的页面，读取其标题和最终 URL，并清理上下文和客户端连接。

import puppeteer from 'puppeteer-core';

const target = process.env.AUTHORIZED_TEST_URL;
if (!target) throw new Error('Set AUTHORIZED_TEST_URL to your permitted test page');
const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9227',
});
try {
  const context = await browser.createBrowserContext();
  try {
    const page = await context.newPage();
    await page.goto(target, { waitUntil: 'domcontentloaded' });
    console.log({ title: await page.title(), url: page.url() });
  } finally {
    await context.close();
  }
} finally {
  await browser.disconnect();
}

输出应标识实际加载的页面。如果输出的是错误页、重定向或无关文档，请先修复这个问题，再构造 CAPTCHA 请求。在简单测试页面上成功执行 JavaScript 是个有用的起点，但这并不能说明真实组件的所有浏览器 API 都受支持。

Puppeteer 的 connect 参考描述了如何附着到现有浏览器。这就是为什么示例使用 connect 而不是启动单独的 Chromium 进程：被测试的进程必须仍然是 Lightpanda。

准备一个有文档的 CAPTCHA 任务

从浏览器实际加载的挑战中构造求解任务，并保持其输入与该页面的关联。

对于标准 reCAPTCHA v2，先阅读官方 v2 任务参考。无代理请求使用 ReCaptchaV2TaskProxyLess、websiteURL 和 websiteKey。其他观察到的参数应放入其文档中的字段；不要只根据可见复选框来推断。

下方 JSON 展示了请求大致结构。它包含占位符，并非实时挑战或已执行的付费请求。请用你自己的被允许页面中的值替换，并使用上述官方 API 或 SDK 示例发送请求。

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://example.com/authorized-form",
    "websiteKey": "PUBLIC_SITE_KEY_FROM_THIS_PAGE"
  }
}

将 clientKey 保留在后端进程中。它不是浏览器侧站点密钥，不应插入页面中。websiteURL 应描述加载 CAPTCHA 的网页，而不是 CAPTCHA iframe URL 或 Lightpanda 控制端点。

如果你不知道版本或附加参数，请在检查被允许页面时使用有文档的CAPTCHA 参数检测流程。那只是准备步骤；并不意味着可以在 Lightpanda 中加载 Chrome 扩展。

兑换你的 CapSolver 奖励码

即时提升你的自动化预算！
在为 CapSolver 账号充值时使用奖励码 CAP26，每次充值可额外获得 5% 奖励——无次数上限。
现在就在你的 CapSolver 控制台 中兑换

在不替换页面的情况下获取求解结果

在任务 API 处理期间保持 Lightpanda 页面及其应用状态存活。

对于异步响应，保留 createTask 返回的任务 ID，并使用对应任务调用 getTaskResult。在读取解答前先检查 API 错误和处理状态。该 v2 结果中记录的响应令牌字段是 gRecaptchaResponse。

不要仅因为求解请求完成就创建新的浏览器上下文。新的上下文意味着不同的页面环境，而你的应用可能有属于原始操作的状态。同样，不要把一个结果复用到另一个挂起页面上，只因为那个页面碰巧显示同类组件。

上面的仅连接脚本是有意关闭上下文的。在把求解执行集成进真实应用时，应将求解步骤和页面专属的后续操作放在该上下文生命周期内，在清理逻辑运行前完成。同时在出现错误时也要保留清理行为。

使用应用自有的令牌传递方式

通过你自己的应用定义的回调或提交流程来应用结果。不存在对所有页面都通用的回调名称。不要往集成中粘贴一个拍脑袋的函数就以为表单已经接受了这个值。

可以先在自有的测试夹具上用一个无效字符串检查一个最小浏览器侧适配器：验证预期回调是否收到了该字符串，并且相关字段发生了变化。这只验证了适配器本身，不能用这个无效字符串当作有效 CAPTCHA 响应去提交。

Google 的 reCAPTCHA 响应验证指南解释了单独的应用端验证步骤。在传回真实求解结果后，需要检查同一次尝试对应的应用结果。字段被填充或者回调被调用，并不足以证明成功。

按出错组件诊断失败

将浏览器加载、求解器执行和应用接受分开，这样重试才能针对真实问题。

Puppeteer 无法连接

确认 Lightpanda 进程仍在运行，主机和端口一致。在假设一个可用的 Chromium 脚本与当前 Lightpanda 构建兼容之前，检查固定的客户端和浏览器版本。

页面加载但 CAPTCHA 组件未显示

检查页面脚本错误及组件的网络请求。求解器 API 无法修复页面所依赖但浏览器引擎不支持的功能。在进行付费任务前，证明被授权页面确实加载了预期挑战。

任务 API 拒绝请求

阅读文档中的错误响应，并检查密钥、任务类型、URL、站点密钥以及条件字段。认证错误只说明 API 有响应；并不能证明求解集成成功。不要反复提交同一份无效输入。

求解器返回了令牌但应用拒绝它

检查页面归属、令牌传递、回调行为和服务端验证。记录任务 ID 和已脱敏的失败原因。避免在共享构建输出中记录 API 密钥或原始响应令牌。

工作流只在测试夹具上有效

把夹具当作适配器测试。依赖集成之前务必运行实际被允许的 CAPTCHA 流程。浏览器行为、组件脚本和应用验证都是额外条件，单靠成功的 CDP 握手无法自动满足。

判断该集成是否适合你的爬虫

当爬虫已经使用 Lightpanda，在授权任务期间遇到受支持的 CAPTCHA，并且有验证过的方式继续同一页面时，Lightpanda 加外部求解器 API 才有意义。它不是往无 CAPTCHA 的页面里硬加求解器的理由，更不是声称具备通用浏览器兼容性的依据。

先完成真实浏览器连接，验证任务结构，然后在增加并发之前测试一个被允许的应用流程。将每个结果与其请求页面一一对应，并衡量应用的实际结果。

使用 CapSolver 构建可靠的自动化流程

在已验证的 CAPTCHA 检查点使用求解器，然后确认应用端结果。CapSolver 为该步骤提供有文档的求解接口。在扩展集成之前，先在被允许的测试流程上试用 CapSolver。

常见问题

问：这会在 Lightpanda 内部安装 CAPTCHA 求解器吗？

不会。应用通过 CDP 与 Lightpanda 通信，同时单独调用外部求解器 API。随后必须按照授权应用期望的流程来应用结果。

问：我可以把 CapSolver Chrome 扩展加载进这个浏览器吗？

本教程不涉及 Lightpanda 对 Chrome 扩展的支持。它使用的是外部任务 API。在受支持的 Chrome 环境中进行参数检测是单独的准备步骤。

问：Puppeteer 成功连接是否意味着 reCAPTCHA 在 Lightpanda 中可以工作？

不是。它只证明客户端可以连接并运行示例中的浏览器操作。实际的 CAPTCHA 脚本和应用接受情况需要独立测试。

问：JSON 示例使用的是哪种 reCAPTCHA 类型？

示例展示的是标准 reCAPTCHA v2，任务类型为 ReCaptchaV2TaskProxyLess。Enterprise、v3 以及其他挑战类型都需要各自有文档的任务类型和输入。

问：示例代码是否已经完成了一次付费 CAPTCHA 求解？

没有。可执行示例只检查浏览器连接，而 JSON 只是用占位符说明任务结构。测试求解和最终接受还需要有效的求解账号以及一个授权的实时挑战。