reCAPTCHA v3 与 v2：选择交互方式和网站责任

reCAPTCHA v3 与 v2 的实际选择，取决于网站能够承担哪种交互和服务端责任。v2 复选框提供显式交互；隐形 v2 仍可能显示挑战；v3 返回评分，由网站将其转换为应用决策。BotBrowser 提供由 profile 支持的浏览器控制，用于复现客户端环境，但不能选择网站策略、代替网站验证服务商令牌，或向访问者揭示私有评分。已有集成需要为浏览器流程和后台结果分别指定负责人。

这些名称指已有的经典网页集成，包括账户迁移后仍受支持并保留的集成。现行 Google Cloud 密钥文档 将 CHECKBOX 对应到旧版 v2 Checkbox、INVISIBLE 对应到旧版 v2 Invisible、SCORE 对应到旧版 v3。Google 的迁移说明 确认原有网页代码和后台调用可以继续使用。经典指南的弃用提示不等于这些已部署契约停止工作；新的 Cloud 功能和迁移步骤应查阅各自的现行文档。

摘要

• 比较的是三种具体网页集成：v2 复选框、隐形 v2 和 v3。隐形 v2 不是 v3 的另一个名称。
• 每种集成都需要后台令牌验证。浏览器回调成功不等于表单提交已获授权。
• v3 要求网站检查预期 action，并决定返回评分对当前操作意味着什么。移除图片题不会移除这项责任。
• 选择应用能够解释并从失败中恢复的交互，再为服务端检查和应用结果指定负责人。
• Google 经典指南已有弃用提示。现行 Cloud 文档仍对应这些旧版名称并支持原有集成；应确认实际密钥和 API，不能把比较扩大到所有现行产品。

目录

• 已有网页集成的选择矩阵
• 浏览器流程如何改变用户体验
• 后台验证始终必需
• v3 增加 action 和评分策略责任
• 实施责任清单
• 三个假设选择及其失败路径
• 实践结论

已有网页集成的选择矩阵

Google 的版本比较 将 v2 的复选框、隐形形式与 v3 分开。比较针对文档规定的网页集成契约，不是安全效果的实测排名。已经使用其中一种契约的网站，可以通过改变后界面和后台分别要承担什么来评估调整。试图解释一次拒绝的访问者面对的是另一种任务，通常没有完成该选择所需的服务端记录。

术语有现行适用边界。Google 的密钥文档 除了提供上述三种旧版名称与密钥类型的对应关系，还介绍其他集成类型。因此旧名称仍能识别已有实现，但不代表目前的整个产品范围。下面的矩阵适用于明确命名的经典网页流程和相应验证模型，不建议所有新 Cloud 部署默认采用旧 API。

选择字段	v2 复选框	隐形 v2	v3
最初的用户交互	点击显示的复选框	从按钮或 JavaScript API 调用，没有初始复选框点击	针对网站 action 调用，不用 CAPTCHA 任务中断该流程
文档流程中可能出现的挑战	可能立即通过，也可能出现挑战	尽管入口隐形，仍可能出现挑战	返回评分，由网站选择后续响应
浏览器集成责任	渲染正确控件，处理完成、过期和错误	将执行绑定到预期操作，处理完成、过期和错误	针对预期 action 执行，并及时将令牌发送给后台
后台验证责任	通过文档规定的服务端端点验证响应令牌	通过文档规定的服务端端点验证响应令牌	验证响应令牌，并检查预期 action
应用策略责任	按应用规则判断已验证操作是否被允许	按应用规则判断已验证操作是否被允许	结合操作上下文解释评分，并实施网站策略
考虑该契约的理由	显式复选框步骤适合现有用户流程	希望由表单自身按钮触发验证，同时保留挑战路径	网站能够承担上下文评分处理及相应用户或审核路径
应推迟调整的理由	界面无法支持交互或失败恢复状态	团队尚未设计可能出现的挑战和回调状态	尚无人负责 action 验证、评分处理或应用响应

最后两行是工程选择规则，不是 Google 效果声明。例如，没有指定评分处理负责人的团队，不能通过选择不显眼的客户端流程使责任消失。反过来，保留 v2 的团队仍然需要真正的后台验证器。CAPTCHA 分类模型 区分呈现方式与机制；这里新增的决策是应用将实施和维护哪一种文档契约。

已有密钥也需要管理清单。Google 现行的 Classic 迁移说明 表示，受支持的原有集成可以保留网页代码和后台调用，迁移后仍可使用 siteverify。这不等于账户迁移就是把 v2 改成 v3。应分别记录密钥归属、已部署客户端集成和后台端点，再判断真正改变了哪项责任。

浏览器流程如何改变用户体验

对于 v2 复选框，网站渲染控件，让访问者点击。Google 的 v2 显示指南 支持自动渲染，也支持在库加载后显式渲染。这影响应用如何初始化控件，尤其是动态挂载的表单。仅仅显示一个方框，并不能证明提交处理程序会把正确响应令牌附加到正确操作上。

根据版本比较，复选框流程可以立即接受交互，也可以要求额外挑战。应用需要容纳该分支，不能向所有访问者承诺相同点击次数。支持团队还要区分控件从未初始化，与访问者已经进入挑战这两种状态。它们需要不同解释；都不能证明访问者看到了某个数值评分。

隐形 v2 改变入口。Google 的隐形指南 允许自动绑定按钮、程序化绑定按钮或程序化调用。普通提交按钮可以开始检查，不必先点击复选框。但是，该集成仍可能要求挑战。“隐形”并不承诺整个应用流程都没有可见验证，也不会让网站获得 v3 文档规定的评分响应契约。

回调属于表单控制流程。隐形集成可以先进行普通字段验证，再调用验证，并在完成回调后提交。官方隐形示例 展示了这个顺序。实际应用仍要防止无关回调、重复点击或过期的表单状态被当成当前操作已经完成。这是应用的关联要求，不代表 Google 客户端库提供了应用事务管理器。

v3 将执行关联到 action，并返回令牌供后台评估。v3 指南 介绍按钮绑定和程序化调用，并建议在用户执行操作时调用，而不是页面加载时调用，因为令牌会过期。长期打开的结账页不能把首次加载视为永久有效的验证事件。客户端负责人需要识别真正受保护的操作，以及应当获取令牌的时间。

无论保留哪种契约，无障碍访问都属于应用流程的一部分。显示配置 规定语言与 tabindex 控制，隐形指南还介绍徽章位置和回调处理。这些选项不能证明外围表单具有无障碍可用性。需要使用实际配置的控件检查焦点顺序、状态消息和受支持的恢复路径。v3 没有 CAPTCHA 任务，也不能证明应用自行增加的步骤可用；网站负责自己添加的行为。

后台验证始终必需

共同的服务端责任比“浏览器通过了”更具体。Google 的验证指南 要求后台向 https://www.google.com/recaptcha/api/siteverify 发出 POST，携带 secret 和响应令牌。remoteip 在文档中是可选参数。将 secret 留在后台是这项集成的一部分；回调中收到令牌只是客户端向应用交接，不能代替服务商验证请求。

同一指南规定，每个响应令牌有效期两分钟，且只能验证一次。后台将令牌放入无限延迟的任务队列，不能因为当初回调已完成就视为保留了有效验证。已被验证过的令牌也不能作为可重复使用的会话凭证，服务于其他操作。需要新响应时，应用应重新执行文档规定的流程；自身会话和事务控制仍有各自用途。

服务端错误参考 区分 secret 缺失或无效、响应缺失或无效、请求格式不正确，以及 timeout-or-duplicate。最后一个错误包含两种可能：响应太旧，或已经使用过。单凭该错误无法确定是哪一种。负责人可以关联时间和自身验证调用继续调查，但没有相应证据时，不应将文档中的组合错误改写成某个具体浏览器故障。

验证也有响应契约。经典网页响应规定 success、challenge_ts、hostname 和可选 error-codes；v3 响应 还规定 score 和 action。challenge_ts 表示挑战加载时间，不是业务事务完成时间。hostname 提供文档规定的网站上下文，不证明应用已经允许账户登录或结账。设计服务端检查和事件消息时，应保留这些字段含义。

后台负责人需要为验证无法完成的情况声明结果。访问验证端点发生网络超时、响应中 success: false，以及令牌验证后应用拒绝，是三种不同状态。验证协议 定义服务商交互；网站必须决定自己的端点如何报告和处理各状态。未处理的异常或含糊的“重试”消息，不应被默认为已经通过验证并获准访问。

应用授权发生在该交互之后。有效令牌不能证明密码正确、账户符合资格或订单满足网站规则。已有集成切换版本时，仍要保留这些检查，不能用新的客户端回调替代它们。v3 集成指南 明确将上下文处理放在返回评估之后。真正要选择的是后台将收到哪种已验证结果，以及应用将如何处理它。

v3 增加 action 和评分策略责任

v3 的 action 字段是客户端调用与后台预期之间的集成约定。Google 要求检查响应时，确认 action 名称与预期一致。action 指南 还规定名称只能包含字母数字字符、斜杠和下划线，不能针对特定用户。网站应为操作定义名称，而不是将邮箱地址、账户标识或其他用户身份编码到这个字段。

预期值必须来自服务端对操作的理解。仅把调用方提供的 action 名复制到“预期”字段，不能证明它与目标端点一致。对于已有登录操作，后台负责人应在检查返回值前，知道该操作对应哪一个约定 action。这是 Google 预期 action 要求 的推论，不是新增服务商 API，也不表示某个第三方网站正确实施了该检查。

评分是另一个返回字段，不是应用判决。v3 文档 规定范围为 0.0 到 1.0，并举出额外身份验证或审核等上下文响应。选择 v3 因而产生网站策略责任：负责人必须决定各受保护操作的适当响应，以及由谁复核意外结果。不存在适用于所有应用的统一分数界限或浏览器设置配方，能够代替这项决策。

Google 还说明，服务从真实流量中学习，因此预发布环境或刚完成实施时的评分可能不同于生产。接受版本调整时，需要考虑这个环境限定。预发布表单抵达成功页，只能证明声明的预发布集成结果，不能证明生产评分分布或应用策略合适。应区分验证实现是否正确，与后续评估网站运营决策是否恰当。

经典公开说明表示，评分基于与网站的交互，更多上下文包括正常行为与滥用行为。它没有公布完整权重模型，使浏览器客户端能自行计算评分。v3 部署位置指南 说明的是集成，不证明改变某个浏览器属性就会改变具体结果。应用工程师和获授权的自动化运营者使用版本比较时，需要保留这一区别。

可见结果应与服务商结果分开记录。例如，应用可能在评估后要求额外身份验证；没有图片题不等于请求操作立即获得允许。Google 的评分解释示例 展示了这种分离。版本选择应在发布前明确预期应用响应和负责人，不能让产品行为依赖于对收到的任意数值所作的未记录解释。

实施责任清单

下面的清单将矩阵转换为应用团队之间的交接。预期产物是每项选定契约要求的责任，都有明确负责人和记录答案。这是设计清单，不是捕获的服务商响应，也不证明某个已部署网站的行为。Google 的验证要求 和 v3 action 契约 提供服务商义务；应用关联和恢复选择由网站负责。

需要分配的责任	负责人应提供的证据	影响的选择
密钥与集成清单	已配置产品、密钥归属及客户端／后台 API 名称，不共享 secret	确认正在维护哪一种已有契约
浏览器初始化	控件渲染或执行路径、预期受保护操作，以及完成／过期／错误处理	区分复选框、隐形调用和 v3 action 执行
令牌验证	后台如何处理文档要求的验证请求与返回失败状态	每种比较中的集成都需要
预期 action	各受保护端点的服务端 action，以及与 v3 返回字段的对照检查	v3 契约要求
评分响应	应用策略负责人，以及各相关操作支持的结果	使 v3 评估可以执行，又不混淆为授权
应用结果	普通身份验证或事务检查，以及明确的用户结果	服务商验证后仍由网站承担
恢复与支持	区分客户端初始化、响应过期、后台验证和应用拒绝的方法	防止所有失败变成同一个无法解释的验证码错误

客户端初始化值得单独的验收案例。v2 显示指南 要求显式渲染的 onload 回调在 API 加载前已经存在。对于异步加载组件和脚本的应用，这是实际的顺序要求。客户端负责人应验证所选渲染路径，而不是认为网络面板出现 api.js 就证明用户提交时控件已经就绪。库加载事件与表单可用状态，是不同的验收条件。

过期和错误回调也需要可见处理。Google 的隐形配置 规定过期、错误回调，并要求应用在提供错误回调时负责通知用户重试。维护决策应包含消息和允许的恢复动作，不只是回调名。即使客户端展示了有效说明，后台仍要独立处理过期或无效响应。

当团队测试自己获授权的应用时，BotBrowser 的自动化一致性参考 可以支持可重复的浏览器配置。这项能力有助于在声明环境下比较同一个表单行为，但不会实施清单中的服务端责任、签发网站凭据，或从本地浏览器观测确定服务商评分。表单测试应报告实际检查的应用条件；所选集成版本要与访问结果的结论分开记录。

三个假设选择及其失败路径

考虑一个假设的现有支持表单，采用 v2 复选框。负责人希望取消最初的复选框，同时保留可能要求挑战的流程。比较文档中的两种 v2 形式，隐形 v2 就是值得评估的契约。具体工作是按钮调用、回调关联和用户恢复，而后台验证仍必需。把该变化称为“迁到 v3”，会同时误认客户端流程，并错误地引入原本没有新增的 v3 评分策略责任。

再考虑一个假设应用，想为登录 action 使用 v3。客户端能调用 v3，但团队尚未分配预期 action 验证，也没有决定评估需要额外步骤时的响应。Google 的 v3 action 和解释指南 指出了缺少的责任。矩阵的决策是在负责人和应用结果确定前推迟发布，而不是从浏览器回调出现令牌推断已经准备好。这个例子不代表真实服务商运行或实测评分。

最后，假设一个维护中的 v3 集成收到服务商 success: true 响应，但应用拒绝提交。后台应区分令牌验证、返回 action 检查和自身策略结果。v3 响应定义 将它们分成不同字段和责任；success 不是登录成功的承诺。没有相关服务端记录，外部观察者无法判断拒绝涉及 action、账户状态，还是其他应用规则。

即使用户看到相同的普通错误，这些情景也指向不同负责人。初始化失败属于客户端集成；验证请求无效属于后台；有效评估之后按预期限制，则属于应用策略负责人。如果是在第三方网站的一次获授权采集期间出现挑战，运行中 CAPTCHA 排查 承接其请求变化和获准恢复。版本矩阵不授权探查网站的隐藏策略，也不授权越过访问决策继续提取。

常见问题

reCAPTCHA v3 总是比 v2 更好吗？

文档中的契约给网站分配不同工作。v3 在自身流程中移除 CAPTCHA 交互，但需要上下文评分处理和预期 action 验证。v2 复选框与隐形形式仍保留文档规定的挑战可能性。版本说明 不构成适用于所有应用、部署和滥用情景的效果排名。

隐形 reCAPTCHA v2 与 v3 是同一种集成吗？

不是。隐形指南 描述的是仍可能显示挑战的 v2 调用流程。v3 有自己的 action 和评分契约。一个触发验证的按钮，不能识别负责人实际配置了哪种集成。

Siteverify 响应成功就允许操作吗？

它确定的是文档规定的验证结果。应用仍然负责 action 检查、适用的评分策略和普通授权规则。Google 的 v3 响应字段 应与应用最终结果保持区分。

已有经典集成仍能使用这些名称吗？

现行密钥文档 对应旧版名称，Google 的迁移说明 描述原有网页代码和后台调用的延续。应检查实际密钥和集成契约；这些陈述不会将比较扩展到所有 Cloud 功能，也不是迁移步骤。

来源

• Google：选择 reCAPTCHA 类型
• Google：reCAPTCHA v2 显示与配置
• Google：隐形 reCAPTCHA
• Google：reCAPTCHA v3
• Google：验证用户响应
• Google Cloud：reCAPTCHA 密钥与旧版集成名称
• Google Cloud：从 reCAPTCHA Classic 迁移
• BotBrowser：自动化一致性

实践结论

根据应用能支持的交互，以及负责人能实施的后台责任，选择维护中的 v2 或 v3 契约。使用矩阵识别客户端流程，保留必需验证，明确分配 v3 action 与评分决策。版本调整前完成责任清单，再验证实际应用结果。单凭版本标签，既得不到授权策略，也不能证明原有拒绝会消失。