iPhone Safari浏览器出现Google reCAPTCHA V3 'browser-error'问题排查求助

可能原因 #

• Safari隐私设置拦截：部分用户开启了「阻止跨网站跟踪」「智能防跟踪」或启用了内容阻止器，这些设置会拦截reCAPTCHA的跨域请求或脚本执行，触发浏览器层面的错误。
• 网络环境差异：用户使用移动网络（弱信号、基站切换）、运营商劫持或VPN/代理时，reCAPTCHA的请求可能超时或被阻断，而测试环境的稳定WiFi无法复现该场景。
• 浏览器版本/缓存异常：即使是同版本Safari，用户设备可能安装了系统补丁、Beta版更新，或者存在浏览器缓存损坏，导致reCAPTCHA脚本加载异常。
• 调用时机不当：execute()调用过早（比如reCAPTCHA脚本未完全初始化），在页面资源加载缓慢的情况下，会触发请求失败。
• 第三方扩展冲突：用户安装的广告拦截器、隐私保护扩展可能干扰reCAPTCHA的脚本运行或请求发送，引发错误。

解决方法 #

• 规范execute()调用时机：确保在grecaptcha.ready()回调内执行execute()，避免脚本未初始化就发起请求：

  grecaptcha.ready(function() {
    grecaptcha.execute('YOUR_SITE_KEY', {action: 'submit'}).then(function(token) {
      // 处理token或后续逻辑
    }).catch(function(error) {
      // 捕获错误并处理
      if(error.error_code === 'browser-error') {
        // 触发重试逻辑
      }
    });
  });
  

• 添加自动重试机制：捕获browser-error后，实现带间隔的重试逻辑（建议最多3次，每次间隔1-2秒），无需用户手动操作：

  function executeRecaptcha(maxRetries = 3) {
    return new Promise((resolve, reject) => {
      const attempt = () => {
        grecaptcha.execute('YOUR_SITE_KEY', {action: 'submit'})
          .then(resolve)
          .catch(error => {
            if(maxRetries > 0 && error.error_code === 'browser-error') {
              maxRetries--;
              setTimeout(attempt, 1000);
            } else {
              reject(error);
            }
          });
      };
      grecaptcha.ready(attempt);
    });
  }
  

• 引导用户调整浏览器设置：在错误提示中告知用户暂时关闭「阻止跨网站跟踪」，或添加当前网站到内容阻止器的例外列表，同时建议禁用可能干扰的隐私类扩展。
• 优化脚本加载：使用异步方式加载reCAPTCHA脚本，避免阻塞页面资源加载，同时根据用户地区选择合适的脚本源：

  <script src="https://www.recaptcha.net/recaptcha/api.js?render=YOUR_SITE_KEY" async defer></script>
  

• 缓存清理提示：建议用户清除Safari的网站缓存和数据，或在页面响应头中添加缓存控制规则，避免旧脚本缓存导致的异常。
• 收集诊断日志：在前端添加错误日志收集，记录用户的Safari版本、iOS版本、网络类型（移动/WiFi）等信息，帮助定位特定场景下的问题。

内容的提问来源于stack exchange，提问作者Ashok Kumar Ragupathi