React表单中Google reCaptcha初始不显示问题求助

核心原因是Gatsby的客户端路由切换时，不会重新加载全局脚本，而react-google-recaptcha默认仅在页面初始加载时注入Google reCaptcha脚本，后续路由切换时组件渲染脚本未就绪，导致验证码不显示。以下是几种可行的解决方法：

方法一：组件内手动控制脚本加载 #

在组件中主动检查并加载reCaptcha脚本，确保渲染前脚本已就绪：

import React, { useRef, useEffect, useState } from "react"
import ReCAPTCHA from "react-google-recaptcha"

const RecaptchaTest = () => {
  const captchaRef = useRef(null)
  const [scriptLoaded, setScriptLoaded] = useState(false)

  useEffect(() => {
    // 检查全局reCaptcha对象是否存在
    if (!window.grecaptcha) {
      const script = document.createElement('script')
      script.src = `https://www.google.com/recaptcha/api.js?render=${process.env.GATSBY_RECAPTCHA_SITE_KEY}`
      script.async = true
      script.defer = true
      script.onload = () => setScriptLoaded(true)
      document.body.appendChild(script)
    } else {
      setScriptLoaded(true)
      // 重置验证码确保正常渲染
      captchaRef.current?.reset()
    }

    return () => {
      // 路由离开时重置验证码，避免残留状态
      captchaRef.current?.reset()
    }
  }, [])

  return (
    <div>
      {scriptLoaded && (
        <ReCAPTCHA
          sitekey={process.env.GATSBY_RECAPTCHA_SITE_KEY}
          ref={captchaRef}
        />
      )}
    </div>
  )
}

export default RecaptchaTest

方法二：全局路由钩子处理 #

在gatsby-browser.js中添加路由更新钩子，每次路由切换时重置验证码：

// gatsby-browser.js
exports.onRouteUpdate = () => {
  if (window.grecaptcha) {
    // 遍历所有验证码容器并重置
    document.querySelectorAll('.g-recaptcha').forEach(captcha => {
      const widgetId = captcha.getAttribute('data-widget-id')
      widgetId && window.grecaptcha.reset(parseInt(widgetId))
    })
  }
}

额外排查点 #

• 确认GATSBY_RECAPTCHA_SITE_KEY环境变量已正确配置，Gatsby会自动将前缀为GATSBY_的变量暴露给客户端
• 查看浏览器控制台是否有脚本加载错误，比如网络限制导致reCaptcha脚本无法加载
• 升级react-google-recaptcha到最新版本，旧版本可能存在SPA环境下的兼容问题

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