reCAPTCHA v2、v3 与 Enterprise:CapSkip 要发送的字段

recaptcha v2 vs v3 - reCAPTCHA v2 vs v3 vs Enterprise: CapSkip Fields to Send

对于在代码里获取 token 的人来说,reCAPTCHA v2 与 v3 的区别有一个很实用的答案:它决定了哪些字段要放进识别请求。v2 需要 sitekey 和页面地址,v3 还需要一个 action 名称,Enterprise 则是叠加在两者之上的一个标志。本文是请求速查表。关于每个小组件是什么、如何辨认它,请先从 什么是 reCAPTCHA 入手,再回到这里查看字段。

每种 reCAPTCHA 变体需要的 CapSkip 字段

CapSkip 与 2captcha 兼容,所以每种变体都是一个 userrecaptcha 任务,由参数标志决定是哪种变体。这些名称来自 API 文档 ,并已对照 1.7.0 版的 Python 和 Node.js SDK 源码核实过。

变体发送到 in.php 的字段Python 调用Node.js 调用
v2 复选框googlekey, pageurlrecaptcha(sitekey, url)recaptcha(sitekey, url)
v2 隐形加上 invisible=1加上 invisible=1invisible 设为 1 的 options
v3加上 version=v3 和一个 actionversion="v3", action="login"version 设为 v3 并带一个 action 的 options
Enterprise v2加上 enterprise=1加上 enterprise=1enterprise 设为 1 的 options
Enterprise v2 隐形加上 enterprise=1 和 invisible=1两个关键字参数都传两个选项都设置
Enterprise v3加上 version=v3、一个 action 和 enterprise=1三个关键字参数都传三个选项都设置

有三个细节能省下调试时间。第一,API 文档把 action=verify 列为 v3 的默认值。两个 SDK 在你省略 action 时都不会发送它,所以默认值是由应用施加的,我没法测试这一点。如果页面检查 action=login ,就需要你自己传入它。第二,回调不属于请求的一部分:CapSkip 返回 token,对于回调式或隐形的小组件,由你的页面代码带着它去调用回调。第三,API 文档说 v2 Enterprise 页面可能带有一个额外的自定义字符串,放在 s 或 data-s 参数里。如果页面有这个字符串,请把它作为 data-s 字段发送,SDK 以关键字 datas 接受它。

下面是 Python 中的 v2 变体。token 在结果的 code 键下返回。

# pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)
PAGE = "https://example.com/page-with-recaptcha"
KEY = "YOUR_SITEKEY"

# Checkbox v2, then the invisible flavour of v2.
v2 = solver.recaptcha(sitekey=KEY, url=PAGE)
invisible = solver.recaptcha(sitekey=KEY, url=PAGE, invisible=1)

# Enterprise is a flag. Add the page's data-s value if it has one.
ent = solver.recaptcha(sitekey=KEY, url=PAGE, enterprise=1,
                       datas="YOUR_DATA_S")
ent_inv = solver.recaptcha(sitekey=KEY, url=PAGE, enterprise=1, invisible=1)

print(v2["code"][:20])   # token, ready for the form field

对于 v3,你要指明版本,以及页面传给它的 execute 调用的 action。

# pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)
PAGE = "https://example.com/page-with-recaptcha"
KEY = "YOUR_SITEKEY"

v3 = solver.recaptcha(sitekey=KEY, url=PAGE, version="v3", action="login")

# v3 Enterprise adds the same flag as v2 Enterprise.
ent_v3 = solver.recaptcha(sitekey=KEY, url=PAGE, version="v3",
                          action="login", enterprise=1)

print(v3["code"][:20])   # token for the action you named

Node.js SDK 以 options 对象的形式,在 sitekey 和页面地址之后接受同样的选择。

// npm install capskip
const { CapSkip } = require('capskip');

const solver = new CapSkip({ host: '127.0.0.1', port: 8080 });
const PAGE = 'https://example.com/page-with-recaptcha';

(async () => {
  const v3 = await solver.recaptcha('YOUR_SITEKEY', PAGE,
    { version: 'v3', action: 'login' });
  const ent = await solver.recaptcha('YOUR_SITEKEY', PAGE,
    { enterprise: 1, invisible: 1 });
  console.log(v3.code.slice(0, 20), ent.code.slice(0, 20));
})();

两个 SDK 还会在发送任何内容之前拒绝自相矛盾的请求。在 v2 任务上带 action,或在 v3 任务上带 invisible 标志,都会抛出验证异常,这比从失败的表单提交中才发现要省事。

# pip install capskip
from capskip import CapSkip, ValidationException

solver = CapSkip(host="127.0.0.1", port=8080)
PAGE = "https://example.com/page-with-recaptcha"

try:
    # An action only exists on v3, so this v2 task is refused locally.
    solver.recaptcha(sitekey="YOUR_SITEKEY", url=PAGE, action="login")
except ValidationException as err:
    print("refused:", err)

我针对一个模拟的 in.php 和 res.php 运行了这些代码块,不是真正的应用,运行环境是 Python 3.11.7、3.13.7 和 3.14.0,以及 Node.js 24.22.0,全部使用 capskip 1.7.0。模拟服务器记录了每次调用发送的字段,它们与表一致:每次调用都带有 method、sitekey 和页面地址,外加一个由 SDK 填入的显式 enterprise 值(0 或 1),其他变体正好多出所列的那些标志。这证明的是请求的形状,而不是一次真正的识别。

服务器对每种变体检查什么

接收方的差异正是需要这些标志的原因。这张表只比较站点后端能看到的内容。

变体token 的来源后端校验它能读到的字段
v2 复选框小组件,以 g-recaptcha-response 提交经典验证成功与否、挑战时间、主机名
v2 隐形一次 execute 调用或一个绑定的按钮,传给回调经典验证成功与否、挑战时间、主机名
v3一次指明 action 的 execute 调用经典验证增加 score 和 action
Enterprise,基于分数的密钥enterprise 的 execute 调用后端的一次评估token 有效性、action、风险分
Enterprise,复选框密钥由 enterprise 脚本渲染的小组件后端的一次评估token 有效性、风险分

它们共用一条规则:token 的有效期是两分钟,并且只能验证一次。Google 的验证指南对经典端点是这样说的,它的评估指南对 Enterprise 又重复了一遍,所以 这篇关于 token 过期的指南 对每一行都适用。Google 的 v3 文档 还补充说,站点应当把返回的 action 与它预期的 action 对照检查,而它的 评估指南 则说评估应当放在后端进行。

关于 Enterprise 与 v3 的问题:Google 描述了两种 Enterprise 密钥。基于分数的密钥像 v3 一样调用 enterprise 的 execute 函数。复选框密钥像 v2 一样,从 enterprise 脚本渲染一个小组件,并且从不调用它。这就是为什么 Enterprise 是请求里的一个标志,而不是第三个版本。

分数是 Google 的,不是 CapSkip 的选项

Google 给一次 v3 访问打分,从 0.0(很可能是机器人)到 1.0(很可能是良好的交互),并建议把 0.5 作为默认阈值。CapSkip 没有任何设置可以索取分数,所以你的识别代码里没有任何东西能保证一个数值。你能控制的是你传入的 action 和你何时请求。

从页面上读取这些值

sitekey 位于 data-sitekey 属性中,或者位于小组件框架地址的 k 参数里。对于 v3 和基于分数的 Enterprise 密钥,action 是页面 execute 调用中的那个字符串。Enterprise 会通过 enterprise 脚本和对 enterprise 对象的调用显露自己。各变体的识别指南讲得更深入:

从另一台机器调用

CapSkip 是一个 Windows 应用,上面的示例都通过 127.0.0.1 与它通信。如果你的脚本运行在别处,请把 CapSkip 切换到 Server mode,并让 host 设置指向那台 Windows PC。设置指南在 连接设置 部分介绍了这个切换,并建议使用静态公网 IP 以获得稳定的远程访问。Server mode 会让端口对任何地址都可达,因为 CapSkip 每次启动都会为它添加一条允许规则。要限制调用方,请为你不信任的地址添加一条 Windows Firewall 阻止规则。

常见问题

reCAPTCHA v2 和 v3 哪个更难自动化?

两者都不需要不同的工具:都是一个任务,只是标志不同。实际的区别是 v3 没有小组件可看。你要在页面脚本里找到 action,而结果取决于你无法设置的 Google 分数。

v3 会显示挑战吗?

按 Google 的说法不会,它说 v3 从不打断用户。想在低分之后加一个可见步骤的站点,得自己构建。

Enterprise 是 v2 还是 v3?

两者皆可。Enterprise 是产品层级,所以由页面决定风格。在 CapSkip 里,你把 enterprise 标志加到 v2 任务或 v3 任务上,请求的其余部分不变。

我能选择 CapSkip 得到的分数吗?

不能。CapSkip 没有这方面的设置。传入正确的 action,在使用 token 的请求之前才去要 token,并从站点读取结果。

你要识别的是哪一种?

先看页面:一个框或一个隐形触发器表示 v2,带 action 的 execute 调用表示 v3,enterprise 脚本表示在任一种上加了标志。然后在请求表中匹配相应的行。因为 CapSkip 在你自己的 Windows PC 上作为一款 无限量验证码识别工具运行,为每种变体申请新的 token,或在 token 过期后再申请一次,都不会增加账单。