react-google-recaptcha-v3中executeRecaptcha始终返回null问题求助

针对你遇到的executeRecaptcha始终返回null的问题，结合v3版本的特性和你的代码，整理几个常见排查方向：

1. 密钥与域名配置错误 #

• 确认NEXT_PUBLIC_GR_KEY是ReCaptcha v3的密钥，v2和v3密钥不通用，用错会直接导致无法生成token。
• 登录Google ReCaptcha控制台，检查允许的域名列表：本地开发必须添加localhost，生产环境要包含实际业务域名，未在列表内的域名会被Google拒绝生成token。

2. ReCaptcha脚本未加载完成就调用 #

你的代码里虽然判断了!executeRecaptcha就返回，但可能存在脚本还在加载中就触发调用的情况。可以通过recaptchaLoaded状态确认加载完成：

const { executeRecaptcha, recaptchaLoaded } = useGoogleReCaptcha();

// 监听加载状态，加载完成后再启用按钮
useEffect(() => {
  setIsButtonDisabled(!recaptchaLoaded);
}, [recaptchaLoaded]);

确保用户点击按钮时，recaptchaLoaded已经为true，再调用executeRecaptcha。

3. 非用户交互触发调用 #

ReCaptcha v3有反爬机制，必须由用户主动交互（比如点击按钮）触发executeRecaptcha，如果是页面自动加载、定时器触发等非用户操作调用，Google会返回null。检查你的authenticate函数是否确实是在用户点击登录按钮时才执行的。

4. 脚本加载失败 #

打开浏览器控制台的Network面板，查看https://www.google.com/recaptcha/api.js的请求状态：

• 如果请求403或失败，大概率是密钥错误或域名未配置。
• 如果请求成功，但控制台有ReCaptcha相关报错，根据错误信息调整配置。

5. Next.js环境适配问题 #

如果你用的是Next.js App Router，GoogleReCaptchaProvider需要挂载在根layout中，避免上下文失效。如果是Pages Router，当前的包裹方式没问题，但要确保没有其他嵌套的Provider干扰上下文传递。

代码调整建议 #

修改checkRecaptcha函数，增强错误处理：

const checkRecaptcha = async () => {
  try {
    if (!executeRecaptcha) {
      bottomSheet.warning({ message: '验证服务未就绪，请稍后重试' });
      return false;
    }

    if (!isRecaptchaAvailable) return true;

    const token = await executeRecaptcha('login');
    if (!token) {
      bottomSheet.warning({ message: '验证失败，请重试' });
      return false;
    }

    const isRecaptchaValid = await service.validateRecaptcha(token);
    if (!isRecaptchaValid) {
      bottomSheet.error({ message: '验证无效，请重试' });
    }
    return isRecaptchaValid;
  } catch (error) {
    console.error('Recaptcha验证出错:', error);
    bottomSheet.error({ message: '验证服务异常，请稍后重试' });
    return false;
  }
};

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