PAYATHON 2026

生产环境 reCAPTCHA v3 为何给真实用户 0.1 或 0.3 的低分?

数据小陈

点击提交时生成 token 是推荐做法

仅看现有代码,还无法确定为什么会出现大量低分。用户点击提交时调用 grecaptcha.execute 符合 Google 的接入建议,也没有足够证据表明页面放在 <iframe> 中就一定会得到 0.1 或 0.3 的评分。

reCAPTCHA v3 返回风险评分,是否拦截由你们的系统决定。既然接近 80% 的真实用户被拦截,建议先检查验证结果和拦截规则,并为低分登录提供二次验证路径。

Google 建议在受保护操作发生时生成 token,以免用户在页面加载后迟迟不提交,导致 token 过期。脚本可以提前加载,登录 token 则在提交时生成。reCAPTCHA v3 接入说明

先区分低分与验证失败

排查时,先查看后端收到的原始验证字段,确认 0.1 和 0.3 确实来自 Google 的 score,而不是业务代码在超时、字段缺失或解析失败时填入的默认值。

如果使用传统 siteverify 接口,应分别处理以下情况:

  • success 为 false:检查 error-codes,先解决 token 或接入问题。
  • success 为 true,但 action 不是 login:不应当作有效的登录验证结果。
  • hostname 不在服务端允许列表中:检查执行位置、域名配置和请求来源。
  • token 验证通过,且 action、hostname 符合预期,但 score 很低:再排查评分和业务策略。

每个 token 的有效期为两分钟,且只能验证一次。重复使用或过期可能返回 timeout-or-duplicate,不能把这种失败记成一次正常的低分结果。success: true 也不代表评分足以放行。服务端验证说明、v3 响应字段说明

建议记录验证状态、评分、action、hostname、错误码,以及请求来自独立页面还是合作伙伴嵌入页面。日志不要保存密码、secret 或完整 token。

检查 React SPA 中的脚本与提交逻辑

原代码只展示了 execute,没有展示脚本加载和后端验证,不能据此认定完整接入正确。

对于这种通过 site key 调用 execute 的方式,脚本加载形式应为:

<script src="https://www.google.com/recaptcha/api.js?render=MY_SITE_KEY"></script>

在 SPA 中,可以由应用入口统一加载脚本,并检查组件重新渲染或路由切换时是否重复插入脚本、重复绑定提交事件。每次登录提交都应生成一个新的 token,立即随登录请求发送给后端验证。

下面是生成 token 的封装示例,前提是脚本已加载、grecaptcha 已可用:

function getLoginToken() {
  return new Promise((resolve, reject) => {
    grecaptcha.ready(function () {
      grecaptcha.execute('MY_SITE_KEY', { action: 'login' })
        .then(resolve, reject);
    });
  });
}

在实际提交处理函数中,等待 getLoginToken() 完成后再发送登录请求;失败时显示可重试状态,并防止重复提交。site key 可以出现在前端,secret 必须留在服务端。脚本加载示例、验证请求参数

iframe 需要做对照排查

跨站嵌入值得检查,但目前仍是待验证因素。浏览器隐私限制、Cookie 或存储限制、内容拦截扩展、iframe 的 sandbox 配置和 CSP 都需要检查。现有信息无法证明其中某一项导致了低分,也无法量化其影响。

建议比较以下两条访问路径:

  1. 直接打开登录页。
  2. 在合作伙伴网站的 <iframe> 中打开同一个登录页。

尽量保持浏览器、网络和应用版本一致,比较一段真实流量中的评分分布、脚本加载错误和服务端验证结果。单次评分变化不足以确认原因,也不要通过反复执行 execute 来尝试刷高分。

同时确认 reCAPTCHA 代码实际在哪个页面域名下执行,并核对返回的 hostname。不能只根据顶层合作伙伴页面的域名配置允许列表;如果合作伙伴直接托管登录代码,应按实际执行域名检查配置。Google 的域名验证说明要求密钥用于允许的域名,并强调服务端来源校验。域名验证说明

如何帮助模型改善判断

对普通 v3 接入,可以提供正常、持续的生产流量,为不同操作使用清晰的 action,并观察真实业务结果。Google 提醒,流量不足时评分可能不准确;上线初期也不能直接假定评分已经稳定。v3 流量分析说明

也可以评估是否在其他有意义的页面或操作上增加后台执行,以补充上下文。但不要缓存这些 token 用于之后的登录,增加调用也不能保证提高评分。

如果实际使用 Google Cloud 的 Assessment API,并能取得 assessment ID,可以通过 projects.assessments.annotate 回传 LEGITIMATE 或 FRAUDULENT 等反馈。该能力有相应的接入和权限要求,不能直接套用到仅调用传统 siteverify 的代码中。Assessment 标注说明

标注应依赖后续业务证据。例如,二次认证结果可以帮助判断登录是否合法;仅凭密码正确就把所有登录标记为合法并不可靠,因为撞库请求也可能持有正确密码。

低分登录应如何处理

建议将低分登录转入 MFA、邮箱验证等补充校验,同时保留账号和来源维度的速率限制。Google 对登录场景也建议使用这种处理方式。评分处理建议

随后按 login action、独立访问和嵌入访问分别观察评分与二次验证结果,再调整阈值。不要仅为减少投诉就直接放行全部低分请求,也不要承诺等待固定天数后评分就会恢复。

下一步先确认这批请求是否都属于“token 验证成功但评分低”,再检查低分是否集中在 iframe 路径,以便决定是修复接入、调整嵌入环境,还是重新设置登录验证策略。

备注:内容仅供参考。