
Emma Foster
Machine Learning Engineer
已发表 Nov 19, 2026
已更新 Nov 19, 2026 · 最小阅读量

ImageToTextTask 读取本地图片验证码;该任务会在 createTask 响应中直接返回识别结果。errorId,在使用前验证 solution.text 是否有效。验证码识别服务为 Laravel 应用提供了一个服务端步骤,用于在已授权的工作流中处理受支持的挑战。Laravel 是一个 PHP Web 应用框架:它可以运行应用代码、控制台命令和后台任务。它的 HTTP 客户端负责发起 API 请求,但不会渲染浏览器页面或直接操纵验证码控件。
例如,一个内部运营工具在执行已批准的文档获取任务时可能会遇到图片验证码。应用将图片发送给识别服务,检查返回的文本,然后将答案传递给当前工作流中的对应步骤。应用依旧负责会话处理、结果校验以及是否继续执行的决策。
本指南使用 CapSolver 搭配 Laravel 原生 HTTP 客户端。示例仅识别一张自有的本地测试图片,使请求和结果在接入更大应用前更易于检查。本文并非指导你如何在自己的表单上安装验证码防护。
准备一个可正常运行的 Laravel 应用、一个有余额的 CapSolver 账号,以及一张你拥有或被授权处理的本地 PNG/JPEG 图片。将图片放在 storage/app/fixture.png,以便后面的命令使用。选择一张简单的文本图片,便于你自己核对预期答案。
在 Laravel 项目根目录运行命令。本次集成使用框架的 HTTP 客户端,无需单独安装识别服务的 SDK。PHP 必须能与该 API 建立经过验证的 HTTPS 连接。
这里使用的任务类型是 ImageToTextTask。它的 body 字段包含图片的 Base64 数据,不带 data-URI 前缀。module 使用 common 时会返回识别出的文本。与异步任务流程不同,这个识别任务会在 createTask 响应中直接返回结果;本示例不会轮询 getTaskResult。
将 API Key 存入应用的环境变量中,并通过配置文件对外暴露。在服务器上的 .env 文件中添加如下内容,并在本地替换占位符:
CAPSOLVER_API_KEY=YOUR_CAPSOLVER_API_KEY
创建 config/capsolver.php:
<?php
return ['api_key' => env('CAPSOLVER_API_KEY')];
命令会读取 config('capsolver.api_key')。Laravel 的 配置文档 解释了为什么应当把环境变量经由配置文件使用,尤其是在配置被缓存时。如果你的部署启用了配置缓存,在更改 key 之后,按正常部署流程重新构建配置缓存。
不要把 .env 提交到版本控制系统,也不要把 key 暴露给前端 JavaScript。避免记录包含完整请求体的日志:请求体中的 clientKey 字段是凭证,而图片字段也可能包含不适合出现在通用应用日志中的数据。
将以下闭包命令添加到 routes/console.php 中,同时保留文件中已有的其它命令。Laravel 支持 基于闭包的 Artisan 命令;这样可以让首次集成足够小巧,方便直接运行和检查。
该命令会验证本地输入、发送一次请求,并在所有响应检查通过后仅打印非空文本结果。对 PNG/JPEG 的限制以及超时值只是示例应用的选择,并非厂商限制的完整列表。
<?php
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\ConnectionException;
Artisan::command('captcha:read {path}', function () {
$key = config('capsolver.api_key');
$path = $this->argument('path');
if (! is_string($key) || $key === '') {
$this->error('Set CAPSOLVER_API_KEY on the server.');
return 1;
}
if (! is_file($path) || ! is_readable($path)) {
$this->error('Supply a readable local image file.');
return 1;
}
if (! in_array(mime_content_type($path), ['image/png', 'image/jpeg'], true)) {
$this->error('This example accepts PNG and JPEG files.');
return 1;
}
$image = file_get_contents($path);
if ($image === false) {
$this->error('Could not read the image.');
return 1;
}
try {
$response = Http::acceptJson()->connectTimeout(10)->timeout(60)
->post('https://api.capsolver.com/createTask', [
'clientKey' => $key,
'task' => [
'type' => 'ImageToTextTask',
'module' => 'common',
'body' => base64_encode($image),
],
]);
} catch (ConnectionException $exception) {
$this->error('Connection failed or timed out. Check before resubmitting.');
return 1;
}
if (! $response->successful()) {
$this->error('Solver HTTP error: '.$response->status());
return 1;
}
$data = $response->json();
if (! is_array($data) || ($data['errorId'] ?? null) !== 0) {
$this->error('Solver API error: '.($data['errorCode'] ?? 'INVALID_RESPONSE'));
return 1;
}
$text = $data['solution']['text'] ?? null;
if (($data['status'] ?? null) !== 'ready' || ! is_string($text) || $text === '') {
$this->error('No ready text result was returned.');
return 1;
}
$this->line($text);
return 0;
})->purpose('Read an authorized image CAPTCHA with the solver API');
检查 HTTP 状态码很重要,因为 Laravel 并不会为每一个 HTTP 错误响应自动抛出异常。API 层面的检查是分开的:即使 HTTP 响应成功,仍必须包含预期的 errorId、任务状态和结果字段。
该命令刻意避免了自动重试创建任务。连接超时可能导致你无法确定服务端是否收到了原始请求。在重试之前先检查失败原因,尤其当你把此操作放入自带重试策略的队列中时。
领取你的 CapSolver 奖励码
立即提升你的自动化预算!
在为 CapSolver 账号充值时使用奖励码 CAP26,每次充值即可额外获得 5% 奖励金 —— 无次数上限。
现在就前往 CapSolver 控制台 兑换吧。
对本地测试图片运行该命令:
php artisan captcha:read storage/app/fixture.png
对于内容为 583729 的图片,预期输出为:
583729
对比返回文本与实际图片,包括大小写和易混淆字符。非空字符串仅能证明请求产生了结果;它不能代表未来每一张图片都能被准确识别。将目标系统的接收结果作为连接到合法应用工作流时的独立校验步骤。
如果 PHP 报告证书文件或信任存储错误,在重试之前修复该运行环境配置的 CA 证书集合。务必保持 TLS 证书验证处于启用状态。命令中的连接错误提示故意保持简短;更详细的基础设施诊断请单独进行,但不要在诊断输出中泄露凭证或完整请求体。
将输入失败、传输失败、API 错误,以及下游拒绝结果视为不同的结局。这种区分可以防止因缺少文件而触发付费 API 重试,也能避免把应用层校验错误误算为识别服务宕机。
| 结果 | 下一步操作 |
|---|---|
| 缺少 API key | 先修复服务器配置,再发起请求 |
| 文件缺失或不在本示例支持范围内 | 修正输入;不需要调用识别服务 |
| 连接失败或超时 | 检查网络及 TLS 配置,确认后再重试 |
| HTTP 或 API 错误 | 记录状态码或错误码,并根据相关 API 文档处理 |
| 返回了文本结果 | 与图片逐一对比,并校验后续应用步骤 |
当你把该命令改造成队列任务时,确保不要在序列化的任务负载中包含密钥,而是在任务执行时通过配置读取。显式定义任务的重试行为。当你无法确认某个结果是否被目标系统接受时,应向调用方返回“未决”的结果状态。
在更广泛的运维排查中,我们的动态 DNS 代理错误解析介绍了另一种与会话相关的失败情况。那个示例关注的是代理一致性问题,而非图片识别;不要把其中的任务参数用于本命令。
应当根据实际遇到的挑战类型选择任务,而不是把所有验证码都发送到图片识别端点。图片转文本任务的结果是字符串,它不能代替 reCAPTCHA 或 Turnstile 集成所期望的令牌。
使用受支持的 API 任务类型来确定合适的协议。浏览器执行、控件参数和提交到目标网站仍是各自独立的职责。先完成这个小型图片工作流,再构建并测试应用真正需要的具体任务类型。
Laravel 原生 HTTP 客户端足以支持一个简洁、易于检查的识别服务集成。保持请求在服务端发起,遵循文档中的任务结构,并同时校验识别结果及后续应用步骤。在此基础上,CapSolver 就可以稳妥地接入到已授权工作流中的验证码步骤,而不会接管应用的其他部分。
问:我需要安装 Laravel 的验证码识别包吗?
不需要。示例直接使用 Laravel 内置 HTTP 客户端调用 API。额外的封装包是可选的,使用前应核对其是否符合当前任务协议。
问:这会给我的 Laravel 登录表单添加验证码保护吗?
不会。这个命令是通过识别服务 API 识别一张已授权的图片验证码。给你自己的表单添加验证码保护,是与验证码提供商验证服务的另一套集成。
问:这个示例需要轮询 getTaskResult 吗?
不需要。ImageToTextTask 会在 createTask 中直接返回识别结果。其他任务类型可能有不同的结果返回流程,请根据所选任务类型的文档进行实现。
问:这段代码按原样能识别 reCAPTCHA 或 Turnstile 吗?
不能。这段代码发送的是 ImageToTextTask 并期望返回文本。reCAPTCHA 和 Turnstile 需要不同的任务参数和令牌结果,仅修改任务名称是不够的。
问:超时后应该自动重试吗?
不要盲目重复创建相同任务。超时可能发生在请求已经到达服务端之后,因此应先检查失败原因,并在添加自动重试前明确设计一个有边界的重试策略。

Emma Foster
Machine Learning Engineer
Where machine learning meets practical AI tooling.
关于作者