Node.js 中的 GeeTest v4:用 fetch 和类型批量注册

geetest v4 in node.js - GeeTest v4 in Node.js: Batch Sign-Ups With fetch and Types

要在 Node.js 里不借助浏览器识别 GeeTest v4,就从页面上读取一次 captcha_id,用这个 id 和页面地址调用 capskip 包里的 solver.geetestV4(),再把它返回的五个字段以相同的名字放进页面自己发出的那个请求里。下面的脚本用内置的 fetch 为六次注册做了这件事,每次提交识别一次,最后用 Promise.allSettled 收尾。这些任务由 CapSkip GeeTest v4 识别工具 在你自己的 Windows PC 上完成识别,不按次收费。

你需要什么

  • 一台装有 CapSkip 5.0.0 或更高版本的 Windows 机器,据更新日志,这是第一个能识别 GeeTest v4 的版本。
  • Node.js 18 或更高版本,这是 capskip 1.8.0 的 engines 字段所声明的。那是第一个带 geetestV4() 的 SDK 版本。我运行过的版本是 20.11.1、24.22.0 和 25.2.1,所以我从未运行过 Node.js 18 本身。
  • TypeScript,但只用于可选的类型检查。写这篇文章时,npm 解析到的是 typescript 7.0.2,它声明需要 Node.js 16.20 或更高版本,以及 @types/node 26.6.6。
  • 一个带有 GeeTest v4 小组件、并且你被允许自动化操作的注册或登录页面。
  • CapSkip 的地址。Local mode 让它留在 127.0.0.1。Server mode 还接受来自你的网络或公网 IP 的连接, 设置指南 的 Connection Settings 一节介绍了这两种模式。

下面的每次运行都用了我写的两个小服务器,一个模仿 CapSkip API,一个模仿注册页面,所以站点规则是我定的。我测试时,真实的 CapSkip 应用在这台 PC 上没有响应,所以我没有向它发送任何内容,也没有任何 GeeTest 站点看到过请求。凡是依据 CapSkip 文档、SDK 源码或 GeeTest 文档而不是依据一次运行得出的说法,我都会注明。真实站点会在它自己的服务器上,用它的私钥,通过 GeeTest 的 服务端验证 API.

第 1 步:设置文件夹

在一个空文件夹里运行第一个代码块。它会创建 package.json,安装 capskip,并加上用于类型检查的 TypeScript。把 tsconfig 代码块保存为 tsconfig.json。然后把第 2 到第 5 步的四个 JavaScript 代码块按顺序保存为同一个名为 geetest_v4.mjs 的文件。.mjs 扩展名允许使用顶层 await。第一次运行之前,请把 ORIGIN、两个路径和邮箱改成你自己站点的。保持原样的话,脚本会请求 example.com,然后以 "the page answered HTTP 404" 停止。

# Run in an empty folder, in PowerShell or any other shell
npm init -y
npm install capskip
npm install --save-dev typescript @types/node
{
  "compilerOptions": {
    "target": "es2022",
    "module": "node16",
    "moduleResolution": "node16",
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "files": ["geetest_v4.mjs"]
}

有了这个文件,tsc 会把脚本当作带类型的 JavaScript 来读取。这个包自带 GeetestV4Options 和一个 SolveResult,其中的五个 GeeTest 字段都是可选的,所以第 3 步里有一个防护检查。

第 2 步:只读取一次 captcha_id

页面把 id 作为 captchaId 传给 initGeetest4,发往 gcaptcha4.geetest.com/load 的请求把它作为 captcha_id 携带,这一点见 CapSkip 的 极验 v4 API 文档。它对每位访客都是一样的,所以 readCaptchaId 把它的 promise 保存在一个变量里,每次运行只获取一次页面,不管后面跟着多少次提交。它把每个匹配都收集到一个 Set 里,并且拒绝去猜:两个不同的 id,或者一个都没有,会让每次提交都在购买任何识别之前就失败。它还会缓存被拒绝的 promise,所以一次页面超时会让整个运行失败。

// @ts-check
// npm install capskip
import {
  CapSkip, ApiException, NetworkException, TimeoutException, ValidationException,
} from "capskip";

const ORIGIN = "https://example.com";
const PAGE_URL = `${ORIGIN}/signup`; // the page that shows the widget
const API_URL = `${ORIGIN}/api/signup`; // where the page's own submit sends its JSON

// Local mode. In Server mode, use the address of the PC that runs CapSkip.
const solver = new CapSkip({ host: "127.0.0.1", port: 8080 });

/** @type {Promise<string> | undefined} */
let idRead;

// The captcha_id is the same for every visitor, so read it once per run.
function readCaptchaId() {
  idRead ??= (async () => {
    const res = await fetch(PAGE_URL, { signal: AbortSignal.timeout(10_000) });
    if (!res.ok) throw new Error(`the page answered HTTP ${res.status}`);
    const html = await res.text();
    const pattern = /captchaId["']?\s*:\s*["']([0-9a-f]{32})["']|[?&]captcha_id=([0-9a-f]{32})/gi;
    const ids = new Set([...html.matchAll(pattern)].map((m) => (m[1] ?? m[2]).toLowerCase()));
    if (ids.size !== 1) throw new Error(`expected one captcha_id in the page, found ${ids.size}`);
    return [...ids][0];
  })();
  return idRead;
}

在我的模拟页面上,当页面用双引号写出 id、用单引号并且键独占一行、作为 JSON 风格对象里带引号的键,以及出现在 load URL 里时,读出的 id 都是对的。如果页面在真正的 id 旁边的注释里留着一个旧的 id,会以 "found 2" 停止,而脚本在别处构建 id 的页面则以 "found 0" 停止。这个模式要求 32 个十六进制字符,就像文档里的 id 那样。

第 3 步:用带类型的选项要五个字段

调用是 solver.geetestV4(captchaId, url, options)。它提交一个任务,轮询结果,并解析为一个对象。API 文档说,res.php 把这五个值作为一个 JSON 字符串放在它的 request 字段里发送,这就是 code 是字符串的原因:SDK 会对它再解析一次,把 captcha_id、lot_number、pass_token、gen_time 和 captcha_output 复制到结果上,在 GeeTest 无法访问时还会加上 isOffline。按 SDK 源码,无法解析的字符串会让结果保持未展开,并且不抛出任何错误,所以除非五个都在,否则 fiveFields 会抛出异常。

/** @typedef {"slide" | "icon" | "nine" | "word" | "phrase" | "match" | "winlinze" | "svg_seed" | "svg_icon" | "ai"} RiskType */

const NAMES = /** @type {const} */ (["captcha_id", "lot_number", "pass_token", "gen_time", "captcha_output"]);

// All five fields or an error: the SDK hands back an answer it cannot parse untouched.
/** @param {import("capskip").SolveResult} result */
function fiveFields(result) {
  /** @type {Record<string, string>} */
  const fields = {};
  for (const name of NAMES) {
    if (!result[name]) {
      throw new Error(`the answer has no ${name}; code starts: ${String(result.code).slice(0, 40)}`);
    }
    fields[name] = String(result[name]);
  }
  return { fields, offline: result.isOffline === true };
}

/** @param {RiskType} [riskType] */
async function solveOnce(riskType) {
  /** @type {import("capskip").GeetestV4Options & { riskType?: RiskType }} */
  const options = { timeout: 60, polling_interval: 2 }; // both in seconds
  if (riskType) options.riskType = riskType;
  const result = await solver.geetestV4(await readCaptchaId(), PAGE_URL, options);
  return fiveFields(result);
}

有两个名字看起来很像。captcha_id 是 GeeTest 回传的小组件 id,也是要发送的那个。captchaId 是 CapSkip 分配给任务的 id。结果里两个都有,而 SDK 的示例把 captchaId 打印在标签 Captcha ID 下面。在我的模拟服务器上,任务 id 是 102,把它作为 captcha_id 提交被拒绝了。

文档为 riskType 列出了十个值:slide、icon、nine、word、phrase、match、winlinze、svg_seed、svg_icon 和 ai。只有站点允许时 GeeTest 才会采用,而且通常是站点自己的选择优先,所以我无法测试它的效果。SDK 自己的定义把 riskType 类型定为普通字符串,运行时 SDK 也只检查它是不是字符串,所以拼写错误会一路传下去:我的模拟服务器原样收到了 risk_type slid。RiskType typedef 能抓到它,tsc 用错误 TS2345 拒绝了这个调用。它抓不到拼错的选项名,因为选项类型允许其他键。一个叫 risktype 的选项能通过编译,然后 SDK 在运行时把它当作不受支持的参数拒绝了。

timeout 和 polling_interval 选项的单位是秒。不带 timeout 时,使用客户端 300 秒的默认值,并且 SDK 不接受 AbortSignal,所以请设置 timeout,而不是用 signal 去竞争:轮询会随之停止。SDK 只在下一次轮询到期时才检查截止时间。针对始终不回答的模拟服务器,默认间隔 5 时 timeout 5 在 7.9 秒后结束,polling_interval 为 2 时在 5.9 秒后结束。过紧的 timeout 还可能丢掉一个已经完成的答案,下面的表格会说明。请为识别留出余量,再加一个间隔。AsyncCapSkip 是同一个类的另一个名字,因为每个方法本来就返回 promise。

proxy 选项接受一个字符串,或者一个带 type 和 uri 的对象。用字符串时,proxytype 默认是 HTTP,而我的模拟服务器看到对象形式到达时是一个 proxy 值加上 proxytype SOCKS5。它只作用于 CapSkip 的识别,我的 fetch 调用不使用它。CapSkip 文档建议,超出偶尔识别的场景就用代理池。我没有测试任何真实代理。

有十一种错误在任何内容到达我的模拟服务器的 in.php 之前,就被 SDK 用 ValidationException 拒绝了:没有 captcha id,页面地址缺失、是相对地址或是 ftp 地址,v3 的参数 gt 和 challenge,一个 userAgent 选项,一个未知的选项名,一个数字作为 riskType,proxytype SOCKS4,以及一个没有 uri 的 proxy 对象。userAgent 被拒绝这一点值得了解,因为 MTCaptcha 和 Yandex SmartCaptcha 的方法接受它,而 GeeTest v4 不接受。文档说,对于缺少 captcha_id 或不受支持的 proxytype,应用会回答 ERROR_BAD_PARAMETERS,对于缺失或格式错误的页面地址,则回答 ERROR_PAGEURL。对于其他的拒绝,文档没有说明,而 SDK 会先一步拦下它们。

第 4 步:以 JSON 发送这五个字段

CapSkip 文档说,要在页面自己的提交所发出的请求里,用这些名字原样发送这些字段,并且每次提交都要重新识别。我的模拟页面提交的是带邮箱和这五个字段的 JSON,所以 submit 也这样做。如果你的页面发送的是表单,请把请求体换成 new URLSearchParams,并去掉 content type 头。

/**
 * @param {string} email
 * @param {RiskType} [riskType]
 */
async function submit(email, riskType) {
  const { fields, offline } = await solveOnce(riskType); // one solve per submission
  const res = await fetch(API_URL, {
    method: "POST",
    // fetch adds no Origin or Referer by itself, and a CSRF check may want them.
    headers: { "Content-Type": "application/json", Origin: ORIGIN, Referer: PAGE_URL },
    body: JSON.stringify({ email, ...fields }),
    signal: AbortSignal.timeout(10_000),
  });
  const body = (await res.text()).slice(0, 60);
  if (!res.ok) throw new Error(`HTTP ${res.status} ${body}`);
  return `${email}: HTTP ${res.status}${offline ? " (offline pass)" : ""}`;
}

这两个头很重要,因为 fetch 既不加 Origin,也不加 Referer。两个头都去掉后,我的模拟服务器在花掉六次识别之后,用 403 和一个 csrf 错误回答了全部六次提交。只保留两者之一时,它接受了它们。那是我的模拟服务器的规则,而你的站点有它自己的规则,所以在一批提交之前,请先发送一次试验性的提交。

永远不要重复使用答案。我把同样的五个字段发送了两次,我的模拟服务器先回答 200,然后回答 403 captcha used。GeeTest 本身是否接受重放,我无法测试。

isOffline 标志用于 GeeTest 本身无法访问的情况。文档说,此时小组件会在没有挑战的情况下放行,答案里带有设为 true 的 isOffline,而站点在它的服务器上决定是否接受。设置指南解释了 Monitor 标签页里的 Offline pass 标签,而 submit 会把 offline pass 这几个字加到它的结果行里。每隔一个答案就是离线的时,一个拒绝离线 pass 的模拟站点接受了六个里的三个,而接受它们的站点接受了全部六个。

第 5 步:用 Promise.allSettled 处理 Node.js 里的 GeeTest v4

设置指南说,CapSkip 对同一类型同时只识别 Max. Threads 设置所允许的任务数。其他的会等待空闲线程,最多等 Wait Timeout 秒,而你的调用 timeout 同时仍在计时。下面的循环发送 WAVE 次提交,用 Promise.allSettled 等待它们全部完成,然后开始下一波。allSettled 永远不会 reject,所以脚本自己设置退出码,而 describe 把四种 SDK 异常类中的每一种变成一行输出。

const WAVE = 3; // keep this at or below Max. Threads for GeeTest in CapSkip

/** @param {unknown} err */
function describe(err) {
  if (err instanceof ValidationException) return `refused before sending: ${err.message}`;
  if (err instanceof TimeoutException) return `no answer in time: ${err.message}`;
  if (err instanceof NetworkException) return `CapSkip not reachable: ${err.message}`;
  if (err instanceof ApiException) return `CapSkip error: ${err.message}`;
  return err instanceof Error ? err.message : String(err);
}

const emails = [
  "[email protected]", "[email protected]", "[email protected]",
  "[email protected]", "[email protected]", "[email protected]",
];

/** @type {PromiseSettledResult<string>[]} */
const settled = [];
for (let i = 0; i < emails.length; i += WAVE) {
  const wave = emails.slice(i, i + WAVE).map((email) => submit(email));
  settled.push(...(await Promise.allSettled(wave)));
}

settled.forEach((s, i) => {
  console.log(s.status === "fulfilled" ? `ok   ${s.value}` : `FAIL ${emails[i]}: ${describe(s.reason)}`);
});
process.exitCode = settled.every((s) => s.status === "fulfilled") ? 0 : 1;

先检查类型,然后运行它。它会为每个邮箱打印一行。

# Check the types, then run the script
npx tsc
node geetest_v4.mjs

这些行是模拟服务器的结果,来自 Windows 11 上的 Node.js 24.22.0 和 capskip 1.8.0,从进程启动计时到退出。数量在 20.11.1 和 25.2.1 上一致,计时的差异在 0.3 秒以内。

模拟设置脚本的表现
六次提交,识别 2 秒,3 个名额;WAVE 为 3、6 或 1每种情况都是六个成功,分别用时 7.7、5.9 和 22.9 秒;同时最多 3、3 和 1 个任务
调用 timeout 为 4,polling_interval 为 1,识别 2 秒,3 个名额;WAVE 为 3 或 6WAVE 3:六个成功,5.7 秒。WAVE 6:三个成功,三个 "timeout 4 exceeded",出现在 4.9 秒
识别 2 秒,timeout 为 3;polling_interval 为 2 或 12:三个全部 "timeout 3 exceeded",出现在 3.9 秒。1:三个全部成功,2.9 秒
答案始终未就绪,timeout 为 5;polling_interval 为 5、2 或 1TimeoutException 分别出现在 7.9、5.9 和 5.9 秒
去掉 Origin 和 Referer 头在花掉六次识别之后,六次都被 403 csrf 拒绝
同样的五个字段发送两次200,然后 403 "captcha used"
每隔一个答案是离线的;站点拒绝或接受离线 pass三个成功、三个被拒绝,或者六个全部成功
答案不是 JSON,或者缺少 lot_number六个防护检查错误,没有向站点发出请求
前两个任务以 ERROR_CAPTCHA_UNSOLVABLE 结束两行 FAIL,四个成功

当 timeout 很宽松时,分波会多花时间:六次提交同时进行用了 5.9 秒,而每波三个用了 7.7 秒,因为每一波要等它最慢的那个完成,下一波才会开始。当调用 timeout 很紧时,它们才划算,如第二行所示。timeout 为 4 秒时,排在满员队伍后面的三个任务超时了。第三行是丢失的答案:模拟服务器在 2 秒时就有了它,但最后一次轮询发生在 1.8 秒,下一次要到 3.8 秒,已经超过了截止时间。请让 WAVE 不超过 CapSkip 里 GeeTest 那一行的 Max. Threads 值。

常见错误

除非某一行写明已见到,否则它来自 CapSkip 的 极验 v4 API 文档.

错误原因修复
ValidationException在 SDK 内部被拒绝,没有发送任何内容(已见到,十一种情况)读那条消息
ERROR_BAD_PARAMETERS按文档:没有 captcha_id,或者 proxytype 不被接受SDK 会先一步拒绝这两种情况
ERROR_PAGEURL按文档:页面地址缺失或格式错误传入完整的页面地址
ERROR_PROXY_FORMAT按文档:CapSkip 无法解析的代理值使用 IP:PORT 或 login:password@IP:PORT
ERROR_CAPTCHA_UNSOLVABLE按文档:任务无法识别。我的模拟服务器为两个任务制造了它重新运行失败的邮箱
ERROR_KEY_DOES_NOT_EXISTAPI Key Validation 已开启。不带 apiKey 时,SDK 发送了密钥 capskip,而我的模拟服务器拒绝了它把你的密钥作为 apiKey 传入
TimeoutException在 timeout 内没有答案(已见到)调大 timeout,或调小 polling_interval
NetworkException没有任何监听时出现 connect ECONNREFUSED(已见到)启动 CapSkip,检查 host 和 port
站点返回 HTTP 403站点自己的规则:请求头、已被使用的答案或离线 pass与页面自己的请求做比较

常见问题

我可以让脚本运行在和 CapSkip 不同的 PC 上吗?

可以。把 CapSkip 设为 Server mode,并把 host 选项设为它所在 PC 的地址,这是唯一需要改的一行。设置指南指出 Server mode 需要管理员权限。下面是我的建议,不是设置指南里的说法:假定 Server mode 下端口对所有地址开放,为你不预期的机器添加一条 Windows Firewall 阻止规则,并开启 API Key Validation,这样每次调用都必须带上密钥。

一次识别可以用于多次提交吗?

不可以。文档说每次提交都要重新识别,而我的模拟服务器拒绝了重放。

这适用于给出 gt 和 challenge 的页面吗?

不适用,那是 GeeTest v3,而 SDK 会在 v4 调用里拒绝 gt 和 challenge。对于那一代,请按照 Node.js 版 GeeTest v3 指南.

GeeTest v4 在 Node.js 里归结为每次运行读一次 id、每次提交识别一次,以及把五个字段按各自的名字复制过去。被拒绝的提交或第二次识别永远不会产生账单,因为这个 本地验证码识别工具 运行在你自己的 PC 上。 Node.js 验证码识别页面 列出了其他验证码类型。