如何解决reCAPTCHA v2作为v3回退时的重复渲染错误

问题背景 #

在登录流程中结合reCAPTCHA v3（隐形验证）和v2（挑战验证）：当v3验证失败时渲染v2组件，若v2验证失败后用户再次触发登录，v3再次失败时尝试重渲染v2会出现上述报错。之前尝试grecaptcha.reset()仅重置状态、手动移除容器子元素均无效。

解决方案 #

1. 保存Widget ID，复用实例并重置 #

reCAPTCHA v2的grecaptcha.render()会返回一个widget ID，保存这个ID后，后续不需要重新渲染，直接调用grecaptcha.reset(id)重置验证状态即可，同时确保容器可见：

// 全局保存v2的widget ID
let recaptchaV2WidgetId = null;
const recaptchaContainer = document.getElementById('recaptcha-container');

// 初始化/显示v2验证的函数
function initRecaptchaV2() {
  if (!recaptchaV2WidgetId) {
    // 第一次渲染，保存widget ID
    recaptchaV2WidgetId = grecaptcha.render(recaptchaContainer, {
      sitekey: '你的V2站点密钥',
      callback: (token) => {
        // 验证成功后的逻辑：携带token发起登录请求
        submitLoginWithRecaptchaV2(token);
      }
    });
  } else {
    // 已有实例，直接重置并显示容器
    grecaptcha.reset(recaptchaV2WidgetId);
    recaptchaContainer.style.display = 'block';
  }
}

2. 彻底销毁旧实例再重建（必要时） #

如果必须完全销毁旧实例（比如需要修改配置），可以通过替换容器元素的方式实现——因为reCAPTCHA的实例绑定在容器元素上，替换容器后原实例会被清理：

function destroyAndReinitRecaptchaV2() {
  const parent = recaptchaContainer.parentNode;
  // 移除旧容器
  parent.removeChild(recaptchaContainer);
  // 创建新容器
  const newContainer = document.createElement('div');
  newContainer.id = 'recaptcha-container';
  parent.appendChild(newContainer);
  // 重置widget ID并重新渲染
  recaptchaV2WidgetId = grecaptcha.render(newContainer, {
    sitekey: '你的V2站点密钥',
    callback: (token) => {
      submitLoginWithRecaptchaV2(token);
    }
  });
}

3. 优化登录触发逻辑 #

在用户点击登录按钮时，先判断当前是否已经渲染过v2实例：

• 若v3验证失败，先检查recaptchaV2WidgetId是否存在，存在则直接重置显示，不存在才渲染新实例；
• 若v2验证失败，仅需重置状态，无需销毁容器，避免后续重复渲染报错。

为什么之前的方法无效？ #

• grecaptcha.reset()：仅重置验证的勾选状态或挑战状态，不会销毁reCAPTCHA绑定在容器上的实例信息；
• 手动removeChild()：仅移除容器内的验证元素，但容器本身仍被reCAPTCHA标记为"已渲染"，再次调用render时会触发重复渲染报错。

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