Flutter Web集成reCAPTCHA V3无法获取Google Token问题排查

1. 检查reCAPTCHA脚本引入是否正确 #

确保web/index.html中引入的是reCAPTCHA v3版本脚本，且站点密钥与控制台一致，脚本需放在flutter.js之前：

<script src="https://www.google.com/recaptcha/api.js?render=你的站点密钥"></script>
<script src="main.dart.js" type="application/javascript"></script>

注意：必须使用reCAPTCHA v3类型的站点密钥，v2密钥无法兼容v3逻辑。

2. 验证包初始化时机与配置 #

在main.dart中初始化g_recaptcha_v3时，需保证密钥与index.html一致，且初始化操作在runApp前完成：

void main() async {
  await GRecaptchaV3.ready('你的站点密钥');
  runApp(const MyApp());
}

若初始化延迟到runApp之后执行，可能导致包未就绪就调用获取Token方法。

3. 确认域名已加入reCAPTCHA白名单 #

登录Google reCAPTCHA控制台，检查测试域名（如localhost:端口号、127.0.0.1:端口号）是否已添加到域名允许列表。本地测试必须明确添加对应域名，否则会被Google拦截返回Null。

4. 排查获取Token的代码逻辑 #

在RecaptchaPage的按钮点击事件中，确保execute方法的调用符合要求：

onPressed: () async {
  String? token = await GRecaptchaV3.execute('submit');
  if (token == null) {
    print('null returned');
  } else {
    // 发送至C# API的逻辑
  }
},

• action参数必须是合法字符串（无空格、特殊字符）
• 必须在用户主动触发的交互（如按钮点击）中调用execute，reCAPTCHA v3禁止无用户交互的自动调用。

5. 通过浏览器开发者工具排查错误 #

打开浏览器F12开发者工具：

• 在Console标签查看是否有reCAPTCHA相关错误（如密钥无效、域名未授权）
• 在Network标签检查是否有向https://www.google.com/recaptcha/api的请求，查看响应状态与返回内容，定位具体失败原因。

6. 直接测试密钥有效性 #

可以用curl命令验证密钥能否正常验证Token：

curl 'https://www.google.com/recaptcha/api/siteverify' \
  --data 'secret=你的密钥&response=获取到的token&remoteip=用户IP'

如果返回success: false，说明密钥配置或请求参数存在问题。

内容的提问来源于stack exchange，提问作者Agustin Coronel