手动渲染Google reCAPTCHA Enterprise报错：无效站点密钥或api.js未加载

你遇到的报错Error: Invalid site key or not loaded in api.js: "6Lf....."，核心原因是手动显式渲染模式下，调用execute时传入的参数不符合规则，以及渲染后的widget标识使用不当，具体分析和修正如下：

问题根源 #

在自动渲染模式（你第一个正常运行的示例）中，script标签的render参数直接指定了sitekey，此时调用execute可以直接传入sitekey作为标识；但在显式手动渲染模式下，规则完全不同：

• 调用grecaptcha.enterprise.render()会返回一个数字类型的widget ID，这个ID才是后续execute时应该传入的标识，而非sitekey本身
• 如果页面只渲染了一个reCAPTCHA widget，也可以省略第一个参数，直接调用grecaptcha.enterprise.execute({action: 'LOGIN'})

你的代码在onClick函数中传入了sitekey（你写的'KEY_ID'），这不符合显式渲染的调用规则，导致Google验证失败，抛出无效密钥的错误。

另外还要确认两个前置条件：

• 页面上必须存在一个id="recaptcha"的DOM元素，作为render的挂载目标
• onRecaptchaLoadCallback函数必须处于全局作用域（不能被包裹在局部作用域如闭包中）

修正后的代码示例 #

<!-- 引入脚本，指定显式渲染和加载回调 -->
<script src="https://www.google.com/recaptcha/enterprise.js?render=explicit&onload=onRecaptchaLoadCallback"></script>

<!-- 页面上需要有挂载reCAPTCHA的元素 -->
<div id="recaptcha"></div>

<script>
// 全局作用域的加载回调，存储widget ID
let recaptchaWidgetId;

function onRecaptchaLoadCallback(){
  // 渲染widget并保存返回的ID
  recaptchaWidgetId = grecaptcha.enterprise.render('recaptcha', {
        sitekey: "6L...", // 替换为你的实际sitekey
        badge: 'inline',
        size: "invisible",
        callback: function () {
            console.log('recaptcha callback');
        }
    });
}

// 表单提交时执行
function onClick(e) {
  e.preventDefault();
  grecaptcha.enterprise.ready(async () => {
    // 使用保存的widget ID调用execute
    const token = await grecaptcha.enterprise.execute(recaptchaWidgetId, {action: 'LOGIN'});
    // 单widget场景下也可省略ID：const token = await grecaptcha.enterprise.execute({action: 'LOGIN'});
    
    // 后续处理token的逻辑
  });
}
</script>

额外注意事项 #

• 确保sitekey属于reCAPTCHA Enterprise（而非普通reCAPTCHA v2/v3），两类密钥不通用
• 检查当前域名已添加到Google Cloud控制台的reCAPTCHA Enterprise密钥允许列表中
• 显式渲染模式下，script标签的src中只需指定render=explicit，不要同时添加具体sitekey

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