
Ethan Collins
Pattern Recognition Specialist

/createTask 提交 CAPTCHA,然后轮询 /getTaskResult 直到 status === 'ready'。.env 文件中——永远不要硬编码。axios + 轮询循环实现干净、生产就绪的 Node.js 集成。现代网页自动化和数据收集项目经常会遇到中断工作流的 CAPTCHA 挑战。无论您是构建网页爬虫、自动化浏览器任务还是开发 AI 代理,集成一个可靠的 CAPTCHA 求解解决方案都变得至关重要。CapSolver 提供了一个由人工智能驱动的 API,可以程序化处理这些挑战,本指南将指导您从零开始在 JavaScript 中实现它。
自动化流量现在占互联网流量的一半左右,使得机器人检测和 CAPTCHA 挑战在各类网络应用中变得越来越常见。对于构建合法自动化流程的开发者来说,拥有一个可靠的程序化解决方案已不再是可选的——而是核心基础设施的必要要求。
在深入代码之前,了解 CapSolver 如何处理 CAPTCHA 请求有助于您正确设计集成方案。该流程遵循一个简单的模式:提交任务,轮询以完成任务,并接收解决方案。
当您将 CAPTCHA 挑战提交给 CapSolver 时,系统会为其分配一个唯一的任务标识符。您的应用程序会定期轮询服务,直到解决方案就绪。一旦完成,您将收到包含继续自动化流程所需令牌或数据的响应。
CapSolver 支持多种 CAPTCHA 类型,包括 reCAPTCHA v2/v3、Cloudflare Turnstile 和图像转文本挑战。API 工作流程在挑战类型之间保持一致,尽管任务参数会根据所需的特定解决方案而变化。有关支持的任务类型的完整列表,请参阅 CapSolver 任务类型参考。如果您是该平台的新手,入门指南 涵盖了账户设置和您的首次 API 调用。有关 CapSolver 如何融入实际爬虫流程的更广泛概述,请参阅 如何将 CapSolver 集成到您的自动化工作流中。
本指南将指导您如何在 JavaScript 和 Node.js 项目中实现 CapSolver 的 CAPTCHA 求解 API。确保您已安装 Node.js 18+,并准备好从您的账户仪表板获取 CapSolver API 密钥。
项目结构:
capsolver-integration/
├── .env # 环境变量
├── capsolver-client.js # 核心 API 客户端
├── index.js # 使用示例
└── package.json
初始化您的项目并安装依赖项:
mkdir capsolver-integration
cd capsolver-integration
npm init -y
npm install axios dotenv
axios 是一个广泛使用的 Node.js HTTP 客户端,它提供了干净的基于 Promise 的语法和内置的超时处理功能——这些在轮询外部 API 时非常有用。
创建一个 .env 文件来安全地存储您的 API 密钥:
CAPSOLVER_API_KEY=您的 API 密钥
安全提示: 永远不要将您的
.env文件提交到版本控制中。立即将其添加到.gitignore中。泄露的 API 密钥可能导致未经授权的使用和意外的费用。有关自动化项目中处理凭证的最佳实践,请参阅 OWASP 密钥管理指南。
您集成的基础是一个可重用的客户端,用于处理认证和请求格式化。该客户端封装了 API 端点,并为每个操作提供方法。将其保存为 capsolver-client.js:
// capsolver-client.js
const axios = require('axios');
class CapSolverClient {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://api.capsolver.com';
}
async request(endpoint, data) {
const response = await axios.post(`${this.baseUrl}${endpoint}`, {
...data,
clientKey: this.apiKey
}, {
headers: { 'Content-Type': 'application/json' },
timeout: 30000
});
return response.data;
}
delay(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
module.exports = CapSolverClient;
注意: 本指南中的代码示例基于 CapSolver 的文档 API 结构展示实现模式。请始终根据 官方 CapSolver API 文档 验证最新的端点路径、任务类型名称和请求/响应格式,因为这些细节可能会发生变化。
此客户端处理 API 通信的重复性任务,包括设置头部和将请求体格式化为包含您的客户端密钥。
在大规模求解 CAPTCHA 之前,确认您的账户有足够的积分。CapSolver 采用按成功解决方案计费的模式,因此检查余额可以防止在工作流中途出现意外失败。
// 添加到 CapSolverClient 类
async getBalance() {
const result = await this.request('/getBalance', {});
if (result.errorCode) {
throw new Error(`余额检查失败:${result.errorCode} - ${result.errorDescription}`);
}
return {
balance: result.balance,
currency: result.currency || 'USD'
};
}
许多开发者会将余额检查纳入初始化流程,以在长时间自动化运行开始前快速失败。
reCAPTCHA v2 提供熟悉的复选框挑战或图像选择任务。要解决这些挑战,您需要目标页面的 URL 和嵌入在页面 HTML 中的站点密钥。然后将求解的令牌作为表单或请求的一部分提交。
// 添加到 CapSolverClient 类
async solveReCaptchaV2(websiteUrl, websiteKey) {
const task = {
type: 'RecaptchaV2Task',
websiteURL: websiteUrl,
websiteKey: websiteKey
};
return await this.submitAndWait(task);
}
async submitAndWait(task) {
// 第一步:提交任务
const submitResult = await this.request('/createTask', { task });
if (submitResult.errorCode) {
throw new Error(`任务创建失败:${submitResult.errorCode}`);
}
const taskId = submitResult.taskId;
// 第二步:轮询结果
while (true) {
await this.delay(1500);
const result = await this.request('/getTaskResult', { taskId });
if (result.status === 'ready') {
return result.solution;
}
if (result.status === 'failed') {
throw new Error(`求解失败:${result.errorDescription || '未知错误'}`);
}
// status === 'processing' → 继续轮询
}
}
1.5 秒的轮询间隔在响应速度和 API 速率限制之间取得平衡。status 字段在任务运行时为 processing,在解决方案可用时变为 ready,如果挑战无法求解则为 failed。有关完整响应模式,请参阅 getTaskResult API 参考。
reCAPTCHA v3 的运作方式不同——它在后台运行,并返回一个风险评分,而不是显示视觉挑战。CapSolver 可以求解 v3 挑战,同时允许您指定目标站点所需的最低评分阈值。
// 添加到 CapSolverClient 类
async solveReCaptchaV3(websiteUrl, websiteKey, options = {}) {
const {
pageAction = 'verify',
minScore = 0.9
} = options;
const task = {
type: 'RecaptchaV3Task',
websiteURL: websiteUrl,
websiteKey: websiteKey,
pageAction: pageAction,
minScore: minScore
};
return await this.submitAndWait(task);
}
reCAPTCHA v3 任务通常比 v2 任务完成得更快,因为它们不需要与视觉挑战进行交互。pageAction 参数应与目标页面定义的操作字符串匹配。
Cloudflare Turnstile 挑战在自动化工作流中频繁出现,尤其是在爬取受 Cloudflare 保护的网站时。CapSolver 提供了对这些挑战的专门支持:
// 添加到 CapSolverClient 类
async solveTurnstile(websiteUrl, websiteKey, options = {}) {
const {
pageAction = 'managed',
metadata = {}
} = options;
const task = {
type: 'AntiCloudflareTask',
websiteURL: websiteUrl,
websiteKey: websiteKey,
pageAction: pageAction,
metadata: metadata
};
return await this.submitAndWait(task);
}
有关更高级的 Cloudflare 场景(包括挑战页面和浏览器指纹模拟)的更多信息,请参阅 在无头浏览器中自动化 CAPTCHA 求解的指南。
以下是一个完整的 index.js 示例,演示如何在实际自动化场景中使用客户端:
// index.js
const CapSolverClient = require('./capsolver-client');
require('dotenv').config();
async function main() {
const client = new CapSolverClient(process.env.CAPSOLVER_API_KEY);
try {
// 在开始前检查余额
const { balance, currency } = await client.getBalance();
console.log(`账户余额:${balance} ${currency}`);
if (balance < 0.01) {
throw new Error('余额不足。请为您的 CapSolver 账户充值。');
}
// 示例:求解 reCAPTCHA v2
const solution = await client.solveReCaptchaV2(
'https://example.com/login',
'6Le-wvkAAAAAATBQbZDLjMjqTLV92vP6EXjs'
);
console.log('CAPTCHA 成功求解');
console.log('令牌:', solution.gRecaptchaResponse);
// 将令牌注入您的自动化流程
// await page.evaluate(token => {
// document.getElementById('g-recaptcha-response').value = token;
// }, solution.gRecaptchaResponse);
} catch (error) {
console.error('错误:', error.message);
process.exit(1);
}
}
main();
生产环境的集成需要强大的错误处理。网络问题、临时 API 中断和 CAPTCHA 失败都可能发生,因此实现重试逻辑可以显著提高可靠性:
async function withRetry(operation, maxAttempts = 3, delayMs = 2000) {
let lastError;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return await operation();
} catch (error) {
lastError = error;
console.warn(`尝试 ${attempt}/${maxAttempts} 失败:${error.message}`);
if (attempt < maxAttempts) {
await new Promise(resolve => setTimeout(resolve, delayMs * attempt));
}
}
}
throw lastError;
}
// 使用方式
const solution = await withRetry(() =>
client.solveReCaptchaV2('https://example.com', '您的站点密钥')
);
指数退避策略(delayMs * attempt)可防止在临时故障期间过度请求 API,并给服务恢复时间。
保护您的 API 密钥。 始终从环境变量加载凭证,而不是硬编码。在本地使用 .env 文件,在 CI/CD 管道中使用适当的密钥管理。
设置任务超时。 添加最大轮询持续时间以防止任务卡住时自动化流程无限挂起。120 秒的超时时间涵盖了绝大多数求解场景。
程序化监控您的余额。 对于长时间运行的自动化任务,在启动时检查余额,并在必要时定期检查。这可以防止运行中无声失败。
匹配任务类型与挑战。 使用错误的任务类型是失败的常见原因。在提交任务前,始终检查目标页面的 HTML 以确认 CAPTCHA 类型并提取正确的站点密钥。
遵守速率限制。 避免提交任务的速度超过工作流的处理能力。对任务进行排队并以受控速率处理可带来更稳定的吞吐量。
有关将 CAPTCHA 求解集成到爬虫流程的更广泛视角,请参阅 如何将 CapSolver 集成到您的自动化或爬虫工作流中,其中涵盖了包括 Puppeteer 和 Playwright 在内的其他模式。如果您的项目涉及无头浏览器,在无头浏览器中自动化 CAPTCHA 求解 将通过端到端的完整设置进行讲解。
问:使用 CapSolver API 是否需要代理?
答:不需要。对于大多数任务类型,CapSolver 会在其基础设施上自行处理求解,您只需传递目标 URL 和站点密钥即可。代理配置是可选的,仅在某些需要从特定 IP 模拟浏览器会话的任务变体中才需要。有关详细信息,请参阅 代理使用指南。
问:求解 CAPTCHA 需要多长时间?
答:求解时间因挑战类型而异。reCAPTCHA v3 通常在 5 秒内解决。reCAPTCHA v2 和 Cloudflare Turnstile 可能需要 10–30 秒,具体取决于挑战难度和当前队列负载。本指南中的轮询循环会自动处理可变的求解时间。
问:如果我的余额在运行过程中耗尽会发生什么?
答:在下一次调用 /createTask 时,API 会返回错误代码。本指南中的客户端会在这种情况下抛出错误,您可以捕获并处理它——例如,发送警报或暂停任务。如指南中所示,在启动时检查余额是防止这种情况的最简单方法。
问:我可以将此客户端用于浏览器(前端 JavaScript)吗?
答:不可以。您的 API 密钥必须保留在服务器端。在前端代码中暴露它将允许任何人使用您的积分。始终从 Node.js 后端、无服务器函数或其他服务器端环境调用 CapSolver API。
问:如果任务返回 failed 我该怎么办?
A:failed 状态通常表示验证参数有误(错误的网站密钥、任务类型不匹配或不支持的页面配置)。检查响应中的 errorDescription 字段,确认您的任务参数是否符合 任务类型文档,并使用更正后的参数重试。您也可以查看 CapSolver 常见问题 了解常见的错误模式。
Q:是否有官方的 JavaScript/Node.js SDK?
A:CapSolver 为多种语言提供了官方 SDK。对于 JavaScript 项目,您可以直接使用本指南中的模式,或查看 CapSolver GitHub 上是否有已发布的 npm 包和代码示例。
通过此实现,您已为在 JavaScript 自动化项目中添加 CAPTCHA 求解功能打下了坚实的基础。您可以扩展此客户端以支持其他任务类型,将其与浏览器自动化工具如 Puppeteer 或 Playwright 集成,或将其与 AI 抓取流程 结合,构建更高级的数据提取管道。
有关其他挑战类型及其特定参数,请参考 官方任务类型文档。
今天就通过 CapSolver 在您的 JavaScript 项目中开始解决 CAPTCHA 吧——创建您的账户,获取您的 API 密钥,并将上述客户端代码放入您的下一个自动化项目中。
了解智能浏览器如何从被动显示工具转变为活跃的数字代理。学习它们的架构、意图理解和动态适应。
