集成Google reCAPTCHA Enterprise到Next.js应用时非测试密钥返回Token为null问题

核心原因分析 #

测试密钥（如6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI）是Google官方提供的通用测试密钥，默认允许所有域名调用且跳过严格验证；而非测试的reCAPTCHA Enterprise密钥需要在Google Cloud控制台完成域名绑定、密钥类型匹配等配置，否则会直接返回null。

具体排查步骤 #

• 检查密钥类型是否正确
  确保你在Google Cloud控制台创建的是reCAPTCHA Enterprise密钥，而非普通reCAPTCHA（v2/v3）密钥。两者验证机制不同，混用会导致token无法生成。

• 验证域名白名单配置
  登录Google Cloud控制台，找到你的reCAPTCHA Enterprise密钥配置页面，确认当前应用的域名（包括开发环境的localhost、生产环境的正式域名）已添加到允许的域名列表中。注意域名不需要加http/https，直接填localhost或yourdomain.com即可。

• 检查代码中的集成方式
  查看登录页面代码，确认是否按照reCAPTCHA Enterprise的要求集成：

  1. 加载脚本时需指定enterprise参数：

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

     而非普通reCAPTCHA的脚本：https://www.google.com/recaptcha/api.js
  2. 调用验证接口时需使用Enterprise的专属方法：

     grecaptcha.enterprise.execute('YOUR_SITE_KEY', { action: 'login' })
       .then(token => {
         // 处理生成的token
       });
     

     不要使用普通的grecaptcha.execute方法。

• 确认密钥是否正确配置到环境变量
  检查Next.js的环境变量（如.env.local）中，非测试环境的密钥是否正确填写，避免存在拼写错误或多余空格。

额外注意事项 #

• 开发环境下使用localhost时，需确保密钥配置中已添加localhost（不需要端口号）；
• 若使用第三方React组件（如react-google-recaptcha），需确认组件支持reCAPTCHA Enterprise，或手动配置参数启用Enterprise模式。

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