
Ethan Collins
AI Agent Workflow Engineer
已发表 May 20, 2026
已更新 May 20, 2026 · 最小阅读量

/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 密钥,并将上述客户端代码放入您的下一个自动化项目中。

Ethan Collins
AI Agent Workflow Engineer
Building clearer handoffs between AI agents and tools.
关于作者