图像CAPTCHA求解器在Node.js中：逐步指南

概要

• 图像CAPTCHA求解器接受图像字节并返回识别的字符，而不是reCAPTCHA令牌。
• 在Node.js中，将图像读取为Buffer并将其编码为Base64以进行ImageToTextTask请求。
• 记录的图像识别流程从createTask返回solution.text；此示例不进行轮询。
• 将您的求解API密钥保留在服务器上，并使用您拥有或被授权测试的表单中的当前图像。
• 下面的Node.js适配器经过模拟响应测试。实际求解和真实表单的接受仍需要在您的环境中进行验证。

图像CAPTCHA集成始于一个影响整个实现的区别：输入是图像文件，有用输出是文本。当Node.js测试运行器遇到包含扭曲字符的表单时，它需要这些字符用于该特定尝试。一个基于令牌的reCAPTCHA示例解决不同的任务。

本指南使用记录的CapSolver图像识别请求和一个小型Node.js适配器，展示文件如何成为请求正文以及答案出现在何处。该示例假设一个拥有测试表单，并且可以本地保存图像。浏览器导航和应用程序特定的表单提交仍然是您的测试运行器的一部分。

图像CAPTCHA求解器返回什么？

图像CAPTCHA求解器返回其在提交的图像中识别的字符。CAPTCHA术语表条目提供了更广泛的背景；此实现涉及文本图像而非交互式小部件。

官方ImageToTextTask文档定义了一个包含类型、Base64图像在body中和识别模块的任务。成功的就绪响应在solution.text中暴露识别的文本。对于此流程，初始createTask响应包含结果。

连接示例到表单时，保持这些值分开：

识别结果是中间结果。应用程序仍可能拒绝答案，如果挑战已更改、会话过期或答案属于另一张图像。

步骤1：准备Node.js和拥有测试图像

使用具有内置fetch和AbortSignal.timeout的Node.js版本；适配器在Node.js 24.16.0上进行了测试。不需要npm依赖。将下面的两个JavaScript文件保存在同一目录中，并将一个非敏感测试图像放在它们旁边。

示例读取./captcha.png。这是一个本地路径，不是图像URL或编码字符串。在调试API调用前检查文件：以PNG扩展名保存的HTML错误页面仍然是HTML页面。使用服务支持的有效图像。

从您的CapSolver账户获取求解API密钥，并通过环境或密钥管理器将其暴露给进程作为CAPSOLVER_API_KEY。将该凭证保留在浏览器JavaScript和源代码控制之外。管理发布或MCP凭证不能替代求解API密钥。

保留与图像关联的表单会话。每当表单生成新挑战时，保存新图像。在另一个请求使用先前表单时覆盖共享文件名可能会为错误尝试生成有效识别响应。为并发尝试提供单独文件或单独保留其字节。

步骤2：将图像字节编码为Base64

将图像作为二进制数据读取，然后对结果Buffer进行编码。Node的文件系统文档描述了readFile，其Buffer文档定义了Base64编码。

下面的关键表达式是image.toString('base64')。不要首先将文件作为UTF-8读取：图像字节不是文本文档。也不要将文件名作为task.body发送。远程服务需要编码内容，而不是您计算机上的路径。

发送原始Base64，不要带有data:image/png;base64,前缀。数据URL在浏览器中有用，但与识别文档中显示的任务正文不同。从Buffer生成编码可避免复制无关前缀或换行符。

此示例拒绝空文件。它不验证图像格式、尺寸或视觉质量。如果您的应用程序接受任意上传，请在此函数之前验证它们。成功的读取仅表示字节可用。

步骤3：发送ImageToTextTask请求

将此适配器保存为recognize-image.mjs。端点和任务字段遵循官方文档。文件加载、超时和响应检查是此示例的附加内容。适配器使用模拟响应运行；将其用于真实服务需要您的求解密钥，并且仍然是一个实时验证步骤。

import { readFile } from 'node:fs/promises';

// 请求字段遵循官方ImageToTextTask文档。
export async function recognizeImage(path, apiKey, request = fetch) {
  if (!apiKey) throw new Error('请先设置CAPSOLVER_API_KEY。');
  const image = await readFile(path);
  if (!image.length) throw new Error('图像文件为空。');

  const response = await request('https://api.capsolver.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    signal: AbortSignal.timeout(60000),
    body: JSON.stringify({
      clientKey: apiKey,
      task: {
        type: 'ImageToTextTask',
        module: 'common',
        body: image.toString('base64')
      }
    })
  });
  if (!response.ok) throw new Error('HTTP状态 ' + response.status);
  const result = await response.json();
  if (result.errorId !== 0) {
    throw new Error(result.errorCode || '图像识别失败。');
  }
  if (result.status !== 'ready' ||
      typeof result.solution?.text !== 'string' ||
      !result.solution.text.length) {
    throw new Error('API未返回识别的文本。');
  }
  return result.solution.text;
}

该函数接受路径和API密钥并返回识别的文本。其第三个参数允许测试替换fetch；正常调用者省略它。60秒的超时是本地设置，不是承诺的识别时间或服务限制。

响应检查遵循请求的各个阶段。失败的HTTP状态在解析前失败。无效的JSON会引发解析错误。提供者错误通过errorId处理。成功的封装仍必须包含就绪结果和非空文本，以防止缺失答案静默成为空表单值。

没有自动重试请求。在传输失败后，客户端可能不知道服务是否收到原始任务。在添加重试之前决定如何处理这种不确定性。

领取您的CapSolver优惠码

立即提升您的自动化预算！
在充值CapSolver账户时使用优惠码 CAP26，每次充值可额外获得 5% 的奖励——无限制。
现在在您的 CapSolver仪表板 中领取

步骤4：运行适配器并使用文本

将以下入口点保存为run.mjs，与适配器并列。其实时请求需要您自己的求解密钥；本地适配器测试不建立完整的实时求解：

import { recognizeImage } from './recognize-image.mjs';

try {
  const path = process.argv[2];
  if (!path) throw new Error('用法：node run.mjs ./captcha.png');
  const text = await recognizeImage(path, process.env.CAPSOLVER_API_KEY);
  console.log(text); // 在此处仅使用非敏感的拥有测试图像。
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

在您的环境中具有求解密钥后，运行以下命令。本指南未进行实时调用：

node run.mjs ./captcha.png

成功的调用将打印返回的文本。答案取决于您的图像；实时调用没有固定预期值。在此终端示例中使用非敏感的拥有固定装置，并避免在共享应用程序日志中打印挑战答案。

在测试运行器中，调用recognizeImage并将返回值发送到与同一图像关联的答案字段。选择器和提交方法属于您的应用程序，因此此处不发明。提交后断言实际表单结果，例如预期的测试记录被接受。

除非表单明确定义标准化，否则保留识别的字符串。将每个答案转换为大写或删除空格可能会改变其含义。已知的字符集可以帮助识别意外结果，但验证不应静默重写不确定的字符。

如何选择识别模块？

根据服务描述的图像任务选择模块。此请求显式使用common。在选择专用模式前，请查阅ImageToTextTask文档中的模块描述。

模块无法修复不相关的输入。整个表单的截图、过时的挑战或包含不相关文本的图像可能无论设置如何都会产生不合适的答案。首先确认提交的字节对应于预期的挑战和活动尝试。

如果您的应用程序生成多种图像样式，请为每种样式使用代表性的拥有样本。将预期答案从您的固定装置中单独保留，以识别答案。这使不匹配可重复，而无需将合成编码检查作为识别准确性的证据。

例如，固定装置可以断言精确的文件字节在Base64编码和解码后存活。单独的识别检查将提供商的答案与固定装置的已知字符进行比较。第三个测试通过表单提交该答案。这些测试回答不同的问题，并应报告单独的结果。

哪些故障应首先调查？

在识别质量之前，调查本地输入故障。无法读取的路径、空文件或缺失密钥意味着请求未成功完成。更改识别模块无法解决这些故障。

对于远程故障，保留提供者错误代码到受控诊断记录中，并查阅官方API错误参考。避免转储请求正文，其中包含凭证和图像。而是记录失败阶段和错误标识符。

Node的全局API文档涵盖了此处使用的请求和中止原语。结束本地等待不会建立远程处理已被取消。

报告问题时，描述哪个阶段失败。“文件读取失败”和“服务返回的文本被表单拒绝”需要不同的证据。除非受控支持流程明确需要，否则将凭证和图像内容保留在共享报告之外。

在使用实时CAPTCHA前进行了哪些测试？

适配器在七个本地测试用例中运行，涵盖请求构建和Base64保留、缺失凭证、空输入、HTTP故障、提供者错误、缺失结果和格式错误或失败的响应。某些案例组合相关断言。测试替换了fetch，因此它们未接触付费服务。

图像固定装置检查编码，答案是提供的测试值。这些检查建立本地JavaScript行为。它们不衡量识别准确性或证明真实表单的接受。在依赖集成前，使用您的求解密钥和当前拥有挑战完成这些检查。

对于同一应用程序中的令牌任务，请使用单独的JavaScript CAPTCHA API指南。将图像识别保留在其自己的分支中，因为结果类型和记录的检索流程不同。使用代表性的拥有图像尝试CapSolver以验证最终连接。

常见问题

Q: 我需要npm包吗？

适配器使用内置的Node.js API，不需要npm包。您仍需要兼容的运行时、有效图像和求解密钥。本地测试使用Node.js 24.16.0。

Q: ImageToTextTask应使用getTaskResult吗？

记录的识别流程从createTask返回带有solution.text的就绪结果。此适配器不进行轮询。来自其他CAPTCHA任务的轮询循环不应自动复制。

Q: 我可以发送图像URL而不是Base64吗？

此记录的请求在body字段中使用编码的图像内容。通过您的应用程序获取拥有图像并对其字节进行编码。文件名或URL不等同于该值。

Q: 为什么表单可能拒绝识别的文本？

检查图像和会话是否属于同一尝试，并且答案未被更改。返回的字符串既不建立识别正确性也不保证应用接受。

Q: 本地测试证明识别准确性吗？

不。它们使用提供的响应来验证适配器的行为。识别和端到端接受需要针对实时服务和您的拥有表单的单独测试。在依赖集成前，使用您的求解密钥和当前拥有挑战完成这些测试。