Rails中recaptcha_tags用reCAPTCHA v3密钥报错，是否仅支持v2？如何配置v3？

关于recaptcha_tags的支持情况 #

recaptcha_tags是专门为reCAPTCHA v2设计的视图辅助方法，会渲染v2专属的验证码交互组件，完全不兼容v3密钥，这就是你触发"Invalid key type"错误的核心原因。

reCAPTCHA v3在Rails中的正确配置步骤 #

1. 确认Gem支持 #

确保项目使用的recaptcha Gem为最新版本（当前主流版本已全面支持v3），若未添加，先在Gemfile中声明：

gem 'recaptcha', require: 'recaptcha/rails'

执行bundle install完成安装。

2. 初始化密钥配置 #

在config/initializers/recaptcha.rb中添加v3专属配置，明确指定API版本：

Recaptcha.configure do |config|
  config.site_key = ENV['RECAPTCHA_V3_SITE_KEY'] # 从环境变量读取站点密钥
  config.secret_key = ENV['RECAPTCHA_V3_SECRET_KEY'] # 从环境变量读取密钥
  config.api_version = 'v3'
end

建议将密钥存入环境变量，避免硬编码泄露风险。

3. 前端无感知集成 #

reCAPTCHA v3是后台评分机制，无需渲染验证码框，只需在表单提交时获取验证token：

<%= form_with(model: @target_model) do |form| %>
  <!-- 你的业务表单字段 -->
  <%= form.hidden_field :recaptcha_token %>

  <%= form.submit "提交", id: "submit-btn" %>
<% end %>

<!-- 加载reCAPTCHA v3脚本 -->
<script src="https://www.google.com/recaptcha/api.js?render=<%= Recaptcha.configuration.site_key %>"></script>

<script>
document.getElementById('submit-btn').addEventListener('click', function(e) {
  e.preventDefault();
  // 执行验证获取token，action名称需与后端验证保持一致
  grecaptcha.execute('<%= Recaptcha.configuration.site_key %>', { action: 'form_submit' }).then(function(token) {
    // 将token存入隐藏字段
    document.querySelector('[name="target_model[recaptcha_token]"]').value = token;
    // 提交表单
    document.querySelector('form').submit();
  });
});
</script>

4. 后端Token验证 #

在控制器的提交动作中，调用verify_recaptcha方法验证token，同时指定对应action和最低评分阈值（v3返回0-1的评分，一般建议设0.5以上）：

def create
  @target_model = TargetModel.new(target_model_params)
  # 验证reCAPTCHA token
  recaptcha_valid = verify_recaptcha(
    action: 'form_submit', # 与前端action名称一致
    minimum_score: 0.5,
    response: params[:target_model][:recaptcha_token]
  )

  if recaptcha_valid && @target_model.save
    redirect_to @target_model, notice: '操作成功'
  else
    # 验证失败时，错误信息自动存入flash[:recaptcha_error]
    render :new
  end
end

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