Android应用ReCaptcha Enterprise密钥停止请求令牌（executes）原因排查

问题场景 #

已按照Google官方文档在Android应用中集成ReCaptcha Enterprise，用于新用户注册流程（用户数据提交至后端API），密钥由Google Cloud生成。核心注册调用代码如下：

private fun registerCall() {
    lifecycleScope.launch {
        recaptchaClient.execute(RecaptchaAction.SIGNUP)
            .onSuccess { captchaToken ->
                registerViewModel.register(
                    name = nameText,
                    surname = lastNameText,
                    email = emailText,
                    password = passwordText,                     
                    captchaToken = captchaToken
                )
            }
            .onFailure { exception ->
                registerFailed(getString(R.string.please_try_again_later))
            }
    }
}

异常现象 #

• Google Cloud控制台可见ReCaptcha请求记录（初始化流程正常）
• 出现验证错误（对应截图显示异常）
• Google Cloud指标显示该密钥已停止生成令牌（无executes记录）

排查方向及解决方案 #

1. 密钥配置校验 #

• 确认密钥类型为Android专用密钥，不可使用网站/其他类型密钥。
• 检查密钥绑定的Android包名与应用AndroidManifest.xml中package字段完全一致（大小写敏感，例如com.example.App与com.example.app不匹配）。

2. 设备与运行环境限制 #

• 避免使用root设备测试：ReCaptcha Enterprise会拦截root设备的验证请求，导致无法生成令牌。
• 使用正式签名包测试：调试签名的应用可能触发ReCaptcha的安全拦截机制，建议用发布版签名包验证。

3. 网络与权限检查 #

• 确保应用已声明INTERNET权限：ReCaptcha需联网完成验证流程。
• 排查网络环境：确认设备可正常访问Google ReCaptcha服务（无代理、防火墙拦截）。

4. 客户端初始化验证 #

• 检查recaptchaClient初始化逻辑：必须在应用生命周期早期（如Application.onCreate()）完成初始化，且使用正确的密钥，避免初始化时出现异常导致客户端实例无效。

5. Google Cloud项目配置 #

• 确认ReCaptcha Enterprise API已在项目中启用（Google Cloud控制台→API库）。
• 检查配额使用情况：若ReCaptcha请求配额耗尽，会停止生成令牌。
• 查看错误日志详情：Google Cloud控制台的错误日志中会显示具体错误码（如invalid-argument、permission-denied），可精准定位问题（例如invalid-argument通常对应密钥/包名不匹配）。

6. Action参数验证 #

• 确认使用的RecaptchaAction.SIGNUP为合法枚举值，未被自定义修改（ReCaptcha Action需符合字符串规范，无特殊字符、长度合规）。

内容的提问来源于stack exchange，提问作者Wojtek K