reCAPTCHA V3返回BROWSER_ERROR及V2令牌为空问题求助

一、reCAPTCHA v2 隐形模式：grecaptcha.execute()无回调、令牌为null且无XHR请求 #

以下是可能的原因及对应解决办法：

• 脚本加载异常
  必须确保页面正确引入带render=explicit参数的v2脚本，同时检查广告拦截器、浏览器安全插件是否屏蔽了脚本加载：

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

• 容器与初始化配置错误
  隐形模式需要先创建隐藏容器，初始化时生成widgetId，调用execute必须传入该ID：

  let widgetId;
  grecaptcha.ready(function() {
    widgetId = grecaptcha.render('recaptcha-hidden-container', {
      'sitekey': '你的站点密钥',
      'size': 'invisible',
      'callback': function(token) {
        // 回调逻辑
      }
    });
  });
  // 触发验证时要传widgetId
  grecaptcha.execute(widgetId);
  

• 域名与运行环境不匹配
  • 禁止用file://协议本地测试，必须用localhost或已备案域名
  • 去Google reCAPTCHA后台核对站点密钥的域名白名单，确认包含当前域名（注意区分http/https）
• 代码执行时机错误
  所有调用grecaptcha相关方法的代码，必须放在grecaptcha.ready()回调内，避免在API未初始化时执行。

二、reCAPTCHA v3：前端获令牌正常，服务端验证报“browser-error” #

这个错误核心是Google判定浏览器环境存在风险，常见原因：

• 浏览器环境触发风险检测
  用户开启隐私模式、代理/VPN，或者页面存在频繁自动化操作（比如短时间重复点击按钮），都会被标记为可疑环境。
• 服务端验证参数缺失
  调用Google验证API时，必须传递用户真实IP的remoteip参数，参数为空或伪造会触发该错误。
• 令牌过期或重复使用
  v3令牌有效期仅2分钟且只能验证一次，检查前端是否延迟提交，或服务端重复验证同一令牌。
• 密钥对不匹配
  确认前端用的v3站点密钥，和服务端用的密钥是同一套，不要和v2的密钥混用，去后台核对密钥类型。

内容的提问来源于stack exchange，提问作者meriem aharchiche