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

对于在代码里获取 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, pageurl | recaptcha(sitekey, url) | recaptcha(sitekey, url) |
| v2 隐形 | 加上 invisible=1 | 加上 invisible=1 | invisible 设为 1 的 options |
| v3 | 加上 version=v3 和一个 action | version="v3", action="login" | version 设为 v3 并带一个 action 的 options |
| Enterprise v2 | 加上 enterprise=1 | 加上 enterprise=1 | enterprise 设为 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 namedNode.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 对象的调用显露自己。各变体的识别指南讲得更深入:
- reCAPTCHA v2 识别工具,适用于复选框、隐形和回调式小组件
- reCAPTCHA v3 识别工具,适用于基于分数的页面
- reCAPTCHA 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 过期后再申请一次,都不会增加账单。
