C# 中的 GeeTest v4:GeetestV4Async 与 IHttpClientFactory

geetest v4 in c# - GeeTest v4 in C#: GeetestV4Async and IHttpClientFactory

要在 C# 里使用 GeeTest v4,先从页面上读出那个公开的 captcha_id,每次表单提交调用一次 CapSkip NuGet 包里的 GeetestV4Async,再把它返回的五个值按各自的名字提交。这篇文章把它搭成一个小型的 .NET 控制台宿主。IHttpClientFactory 提供的类型化 HttpClient 负责和站点通信,一个 CapSkipClient 负责和你自己 Windows PC 上的识别工具通信,一个信号量则避免一批提交同时一起识别。产品方面请看 GeeTest v4 识别工具 页面,识别也不按次收费。

你需要什么

  • 一个列出 GeeTest v4 的 CapSkip 版本,运行在 Windows PC 上。 设置指南 能帮你把它跑起来。我无法确认自己用的应用是哪个版本,因为这台 PC 上的应用没有响应。
  • 需要 需要 .NET 8 SDK 或更高版本,以及 1.8.0 或更高版本的 CapSkip 包,这是第一个带 GeetestV4Async 的版本(更新日志条目日期为 2026-11-16)。这个包本身面向 .NET Standard 2.0,但下面的示例用了 C# 12 语法和 Microsoft.Extensions 包,所以我只在 net8.0 和 net10.0 上运行过。这里只安装了 SDK 10.0.100,所以 net8.0 是通过修改 TargetFramework 那一行来构建,并在 8.0 运行时上运行的。
  • 一个你被允许自动化操作的、显示 GeeTest v4 小组件的页面,以及它提交表单的目标地址。
  • CapSkip 的地址。在 Local mode 下,只有运行它的那台 PC 才能访问 127.0.0.1。Server mode 让其他机器也能访问该 API,两种模式的说明见设置指南的 连接设置.

我测试时无法连上正在运行的 CapSkip 应用,所以没有进行真实的识别,也没有联系任何真实站点。下面的每个结果都来自我写的一个模拟服务器,它扮演 in.php、res.php 和一个带评论表单的站点。这个模拟服务器遵循 SDK 的 API 参考,它的站点规则是我定的,不是 GeeTest 的。凡是依据文档或阅读 SDK 源码得出的说法,我都会注明。

第 1 步:创建宿主和针对该站点的类型化客户端

创建一个项目文件夹并安装这三个包。我只测试了 net8.0 和 net10.0。

dotnet new console -o GeetestWorker
cd GeetestWorker
dotnet add package CapSkip
dotnet add package Microsoft.Extensions.Hosting
dotnet add package Microsoft.Extensions.Http

只有在 net8.0 上,才把最后两条命令换成下面这两条固定版本的命令。最新的 11.0.0 包可以在 net8.0 上构建,但每个包都会打印一条不支持该框架的警告,而固定版本的构建没有任何警告。

# Only on net8.0: use these instead of the two Microsoft.Extensions lines above.
dotnet add package Microsoft.Extensions.Hosting --version 8.0.1
dotnet add package Microsoft.Extensions.Http --version 8.0.1

接下来的三个 C# 代码块是项目文件夹里的文件,每个都以它的文件名开头。请按所示顺序保存。最后一个 Program.cs 会替换模板生成的那个文件。

这个类型化客户端只属于目标站点。阅读 SDK 源码可知,CapSkipClient 在内部自己构建一个静态 HttpClient,没有接受你的 HttpClient 的构造函数,所以 IHttpClientFactory 只对你自己的调用有帮助,对 CapSkip 没有影响。SiteClient 承担两项工作:读取 captcha_id,以及提交表单。

// SiteClient.cs
using System.Text.RegularExpressions;
using CapSkip;

// The typed client talks to the target site only. CapSkipClient has its own HttpClient.
public sealed class SiteClient(HttpClient http)
{
    // Finds captchaId with either quote style, however deeply the call is nested.
    static readonly Regex IdPattern = new(@"captchaId[""']?\s*:\s*[""']([0-9a-fA-F]{32})[""']");

    public async Task<string> ReadCaptchaIdAsync(string pageUrl, CancellationToken ct)
    {
        var html = await http.GetStringAsync(pageUrl, ct);
        var m = IdPattern.Match(html);
        return m.Success ? m.Groups[1].Value : throw new InvalidOperationException("no captchaId on " + pageUrl);
    }

    // The five values go back under GeeTest's own names. "text" is this form's field.
    public async Task<string> PostAsync(string pageUrl, string formUrl, SolveResult r, string text, CancellationToken ct)
    {
        using var form = new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["captcha_id"] = r.GeetestCaptchaId!,
            ["lot_number"] = r.LotNumber!,
            ["pass_token"] = r.PassToken!,
            ["gen_time"] = r.GenTime!,
            ["captcha_output"] = r.CaptchaOutput!,
            ["text"] = text,
        });
        using var request = new HttpRequestMessage(HttpMethod.Post, formUrl) { Content = form };
        request.Headers.Referrer = new Uri(pageUrl);  // many frameworks check it on a form post
        using var response = await http.SendAsync(request, ct);
        return $"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync(ct)}";
    }
}

GeeTest v4 不需要为每个请求获取 challenge,v3 流程则不同,见 用 C# 处理 GeeTest v3 的文章。页面把一个 id(对每位访客都一样)作为 captchaId 传给 initGeetest4,所以你只需读取一次并重复使用。当页面在运行时才构建这个调用时,SDK 文档指向浏览器 Network 标签页里发往 gcaptcha4.geetest.com/load 的请求的 captcha_id 查询参数。这个正则表达式在三个模拟页面上都如我所料地匹配了:一个使用双引号的调用,一个把单引号嵌在两层对象里的调用,以及一个没有 id 的页面,后者抛出了 InvalidOperationException。

客户端有两个细节来自实际运行。工厂会池化它的消息处理程序,默认的处理程序为所有请求保留同一个 cookie 容器:在三次 GET 里,第二次和第三次都带上了上一次响应设置的 cookie。像下面 Program.cs 里那样把 UseCookies 设为 false,就没有任何一次带 cookie(模拟服务器,net10.0 和 net8.0)。如果你的表单需要页面里的会话 cookie,请对每次提交读取 Set-Cookie 并自己把它发回去。HttpClient 自己也不会加 Referer:删掉那一行之后,模拟服务器看到的是一个空的请求头,这就是代码要设置它的原因。

第 2 步:每次提交识别一次

GeetestV4Async 接受 captcha_id、页面地址、一个可选的选项字典和一个 CancellationToken,返回一个 SolveResult。下面的类就是先识别再提交的那个单元,并且用一个 3 个名额的 SemaphoreSlim 限制同时进行的识别数量。请选一个你的 CapSkip PC 能承受的数字,因为三只是我的模拟服务器设置。

// Submitter.cs
using CapSkip;

public sealed class Submitter(CapSkipClient solver, SiteClient site)
{
    // At most 3 solves in flight. Size this to what your CapSkip PC can take.
    readonly SemaphoreSlim gate = new(3);

    public async Task<string> SubmitAsync(string captchaId, string pageUrl, string formUrl, string text, CancellationToken ct)
    {
        SolveResult result;
        await gate.WaitAsync(ct);
        try
        {
            // One solve per submission: this result is used for one form post and dropped.
            result = await solver.GeetestV4Async(captchaId, pageUrl, cancellationToken: ct);
        }
        finally { gate.Release(); }

        // The site decides whether an offline pass counts, so do not send it blindly.
        if (result.IsOffline == true) return "offline pass, not sent";
        return await site.PostAsync(pageUrl, formUrl, result, text, ct);
    }
}

结果以字符串形式带有这五个值:GeetestCaptchaId、LotNumber、PassToken、GenTime 和 CaptchaOutput。第一个之所以不叫 CaptchaId,是因为这个名字已经被 CapSkip 分配给任务的 id 占用了(模拟服务器分配的是 9101 及以上),更新日志对此有说明。Code 保存 API 发送的原始 JSON 字符串,在模拟服务器的运行中,Token 和 Challenge 是 null,因为它们属于其他类型。

为什么每次提交都要识别?SDK 自己的示例说每次提交都要重新识别,我的模拟服务器也强制这一点:把同一个结果提交两次,得到的是 403,响应体写着 pass token 已被使用。那是模拟服务器的规则。我读到的 GeeTest 服务端验证页面没有说一个 pass 能否被使用两次,所以请遵循 SDK 的建议。CapSkip 文档还说要尽快提交,而 GeeTest 页面说过期的 pass_token 验证会失败,这是每次提交都识别的更有力的理由。

谁来检查结果?是站点自己的服务器。根据 GeeTest 服务端验证文档 (该页面是中文的),它会把 lot_number、captcha_output、pass_token 和 gen_time 发给 GeeTest,另外还带上 captcha_id 和一个 sign_token,后者是用站点的私钥对 lot_number 做的 HMAC-SHA256。CapSkip 永远看不到这个密钥,你的代码也不需要它。

IsOffline 是一个可空的 bool。按文档,当 GeeTest 无法访问、它的小组件在没有挑战的情况下放行时,它为 true,之后由站点决定是否接受。SDK 把 true、任意大小写的单词 true 和非零数字读作 true,把零和单词 false 读作 false,把它无法读懂的内容读作 null(模拟服务器的回答,全部六种形式)。上面的代码会跳过离线 pass。如果你的站点接受离线 pass,就删掉那一行。

两个选项都是可选的。这个代码片段替换 Submitter.cs 里的 GeetestV4Async 调用:

// Snippet, not a file: replace the GeetestV4Async call in Submitter.cs with this one.
result = await solver.GeetestV4Async(captchaId, pageUrl, new Dictionary<string, object?>
{
    ["risk_type"] = "slide",
    ["proxy"] = new Proxy("HTTP", "login:[email protected]:8080"),
}, ct);

按文档,risk_type 取十个值之一:slide、icon、nine、word、phrase、match、winlinze、svg_seed、svg_icon 和 ai。只有站点允许调用方选择时,GeeTest 才会采用。SDK 不检查这个值:它会去掉空白,丢弃空值,把一个毫无意义的值原样发出,而对数字则抛出 ValidationException 拒绝。写法 riskType 可以作为别名使用。当站点要求识别和表单提交使用同一个地址时,请使用 proxy,如 验证码识别工具代理文章 所述。不在支持范围(HTTP、HTTPS、SOCKS5 和 SOCKS5H)内的类型会在本地被拒绝,而纯地址字符串默认当作 HTTP 代理。

对于并发的一批请求,也要考虑网络。CapSkip API 文档说,GeeTest 会对网络打分,而来自同一地址的持续请求流正是它的频率限制所针对的。请在 CapSkip 应用的 Settings、Captcha types、GeeTest、Configure Proxies 下添加一个代理池。同一个池同时服务 v3 和 v4,而你随任务发送的代理优先于代理池。

第 3 步:同时运行多次提交

Program.cs 创建宿主只是为了它的依赖容器,所以它从不调用 RunAsync。它只读取一次 captcha_id,同时启动五次提交,并打印每个结果。这五个占位符是你自己的表单文本。请先修改 PageUrl 和 FormUrl,因为按粘贴时的样子,它们指向 example.com,那里没有小组件。

// Program.cs
using CapSkip;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
// Implicit usings import System, which has a TimeoutException too.
using SolverTimeout = CapSkip.TimeoutException;

const string PageUrl = "https://example.com/login";   // the page that shows the widget
const string FormUrl = "https://example.com/comment";  // where its form posts

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.SetMinimumLevel(LogLevel.Warning);  // the host logs every HttpClient call at Information
// Local mode. In Server mode use the server's address, and pass apiKey if validation is on.
builder.Services.AddSingleton(new CapSkipClient(host: "127.0.0.1", port: 8080));
// The factory's pooled handler keeps one cookie jar for every request, so switch it off.
builder.Services.AddHttpClient<SiteClient>(c => c.Timeout = TimeSpan.FromSeconds(20))
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { UseCookies = false });
builder.Services.AddSingleton<Submitter>();
using var host = builder.Build();

using var budget = new CancellationTokenSource(TimeSpan.FromMinutes(2));
Console.CancelKeyPress += (_, e) => { e.Cancel = true; budget.Cancel(); };

var site = host.Services.GetRequiredService<SiteClient>();
var submitter = host.Services.GetRequiredService<Submitter>();
var texts = new[] { "first", "second", "third", "fourth", "fifth" };

string captchaId;
try { captchaId = await site.ReadCaptchaIdAsync(PageUrl, budget.Token); }
catch (Exception ex) { Console.WriteLine("could not read the captcha id: " + ex.Message); return 1; }

var results = await Task.WhenAll(texts.Select(async text =>
{
    try { return await submitter.SubmitAsync(captchaId, PageUrl, FormUrl, text, budget.Token); }
    catch (Exception ex) { return Describe(ex); }  // one failure must not hide the others
}));

for (var i = 0; i < texts.Length; i++) Console.WriteLine($"{texts[i]}: {results[i]}");
return results.All(r => r.StartsWith("200")) ? 0 : 1;

string Describe(Exception ex) => ex switch
{
    // A cancelled submit surfaces as a NetworkException, a cancelled poll as a TaskCanceledException.
    _ when budget.IsCancellationRequested => "the budget ran out",
    ValidationException => "CapSkip refused the arguments: " + ex.Message,
    ApiException => "CapSkip answered " + ex.Message,
    SolverTimeout => "no answer in time: " + ex.Message,
    NetworkException => "CapSkip is not reachable: " + ex.Message,
    // HttpClient reports its own timeout as a TaskCanceledException.
    TaskCanceledException => "the site did not answer within 20 seconds",
    HttpRequestException => "the site could not be reached: " + ex.Message,
    _ => ex.GetType().Name + ": " + ex.Message,
};

每次提交都包在它自己的 try 块里。Task.WhenAll 只会重新抛出第一个失败,而被取消的任务没有可读取的异常,所以在 lambda 内部捕获才能保留每一个结果。用 dotnet run 启动程序。这些行是模拟服务器的结果,在 net10.0 和 net8.0 上完全相同。

模拟设置程序打印的内容
默认的模拟服务器设置五行 200 加上文本,退出码 0
每次识别 2 秒后就绪同时进行的识别最多 3 个,后两次提交比前三次晚 3.8 秒,整个运行大约用了 8 秒
前两次识别失败两行 API 错误,三行 200,退出码 1
模拟站点用 403 拒绝两次表单提交两行 403,三行 200,没有任何重试
每个回答都带有 isOffline true五行离线 pass,未发送,退出码 1

取消和两种 TimeoutException

CancellationToken 同时作用于 SDK 和 HttpClient,所以一个预算覆盖整批请求。模拟服务器永不结束、预算为 3 秒时,五行输出都写着预算已用完,进程大约在 3.5 秒后结束。在 in.php 挂起时取消,得到一个包着 TaskCanceledException 的 NetworkException,在轮询期间取消,则得到一个单独的 TaskCanceledException。在 Describe 里先检查预算 token,就能处理这两种情况。

当轮询超过它的限制时,CapSkip 也会抛出它自己的 TimeoutException,而隐式 using 会导入 System,它也有一个。在 using CapSkip 旁边写一个不带限定的 TimeoutException catch,会因 CS0104 而无法编译,所以 Program.cs 把 SDK 的类别名为 SolverTimeout。不过 HttpClient 不会向你抛出 System.TimeoutException。模拟站点休眠 25 秒、客户端限制为 20 秒时,每次提交都在大约 20 秒后以 TaskCanceledException 返回,整个运行总共用了大约 20.6 秒。

GeetestV4Async 使用 recaptchaTimeout(默认 300 秒),而不是 defaultTimeout(依据更新日志)。我检查过:defaultTimeout 为 1、recaptchaTimeout 为 5,而模拟服务器始终不回答时,异常在 net10.0 上 7.87 秒后到达,在 net8.0 上 7.85 秒后到达。SDK 在大约 0、0.25、0.75、1.75 和 3.75 秒轮询,然后再休眠 4 秒,所以截止时间要到最后那次休眠结束时才被发现,远在你设置的 5 秒之后。

常见错误

你所看到的原因修复
ValidationException在发出任何请求之前就被拒绝:空的 captcha_id,不是绝对 http 或 https 的页面地址,不是字符串的 risk_type,或者来自 v3 的 gt 或 challenge 之类的选项修正参数。重试没有用
带有 ERROR_KEY_DOES_NOT_EXIST 的 ApiException模拟服务器拒绝了这个密钥。按文档,当 API Key Validation 开启且密钥未知时,真实的应用会这样回答在 CapSkipClient 里传入密钥
带 ERROR_CAPTCHA_UNSOLVABLE 的 ApiException识别失败。我是用模拟服务器制造出它的,无法确认真实的应用如何报告 v4 识别失败重新识别,永远不要提交旧的结果
NetworkExceptionCapSkip 的主机和端口上没有任何回应,或者调用被取消了启动 CapSkip,或检查 CapSkipClient 里的 host
CapSkip TimeoutException轮询超过了 recaptchaTimeout,而 SDK 只有在下一次休眠结束时才会发现如果你的识别很慢,就调大 recaptchaTimeout
站点返回 403 或 400在我的模拟服务器里:结果已被使用、缺少某个字段,或者是离线 pass。真实站点有它自己的规则用同一次新的识别结果提交全部五个字段

Server mode:识别工具和宿主在不同的机器上

这个宿主可以运行在第二台 PC 上,而 CapSkip 仍留在你掌控的 Windows 机器上。在识别工具所在 PC 的连接设置里开启 Server mode,然后把那台 PC 的地址填到 CapSkipClient 的 host 参数里。代码里的其他部分都不用改。按设置指南所说,Server mode 需要 CapSkip 以管理员身份运行。设置指南建议使用静态公网 IP 以获得稳定的访问,并对 连接设置 做了完整的说明。

Server mode 启动时,CapSkip 会把它的端口对所有地址开放。要把它限制在你预期的机器上,请为所有其他地址添加一条 Windows Firewall 阻止规则,并开启 API Key Validation,这样 CapSkipClient 就必须出示密钥。

常见问题

为什么结果属性叫 GeetestCaptchaId?

CaptchaId 已被占用:它是 CapSkip 分配给这次识别的 id。GeetestCaptchaId 保存的是小组件回传的 GeeTest captcha_id,它是站点期望收到的五个字段之一。

我可以在多个线程之间共享一个 CapSkipClient 吗?

我在模拟服务器里通过单个实例同时运行了五次识别,没有任何问题,而且源码会在每次调用时复制它的参数。除此之外我没有测试过。如果像上面那样把它注册成单例,限制负载的就是那个信号量。

GeeTest v4 在 C# 里归结为读一次 captcha_id、每次提交调用一次 GeetestV4Async,再把五个字段一起提交。CapSkip 是采用统一授权的 验证码识别工具 并且运行在你自己的 PC 上,所以被拒绝之后每多识别一次都是免费的。.NET 里其他类型见 C# 验证码识别页面,请求格式请阅读 API 文档中的 GeeTest v4 部分.