如何为自定义WordPress注册表单添加reCAPTCHA并修复提交异常？

1. 先开启调试模式定位错误 #

空白页大概率是PHP报错但未显示，先修改wp-config.php开启调试：

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', true );

刷新提交后的页面，就能看到具体错误信息，方便精准排查。

2. 修正reCAPTCHA的前端渲染逻辑 #

若用reCAPTCHA v3： #

• 页面头部加载官方脚本：

<script src="https://www.google.com/recaptcha/api.js?render=你的Site Key"></script>

• 表单里加隐藏token字段，并用JS在提交前获取验证token：

<form id="custom-reg-form" method="post" action="<?php echo esc_url(admin_url('admin-post.php')); ?>">
  <!-- 你的原有注册字段 -->
  <input type="hidden" name="action" value="custom_register">
  <input type="hidden" name="g-recaptcha-response" id="g-recaptcha-response">
  <button type="submit">提交注册</button>
</form>

<script>
document.getElementById('custom-reg-form').addEventListener('submit', function(e) {
  e.preventDefault();
  grecaptcha.ready(function() {
    grecaptcha.execute('你的Site Key', {action: 'register'}).then(function(token) {
      document.getElementById('g-recaptcha-response').value = token;
      document.getElementById('custom-reg-form').submit();
    });
  });
});
</script>

若用reCAPTCHA v2（复选框式，更易实现）： #

• 加载官方脚本：

<script src="https://www.google.com/recaptcha/api.js"></script>

• 表单内添加验证框：

<div class="g-recaptcha" data-sitekey="你的Site Key"></div>

3. 修正后台验证逻辑 #

在functions.php的注册处理函数里，必须先完成reCAPTCHA验证，再处理注册，且所有分支都要做跳转/输出，不能直接中断导致空白：

add_action('admin_post_nopriv_custom_register', 'custom_register_handler');
add_action('admin_post_custom_register', 'custom_register_handler');

function custom_register_handler() {
  // 验证reCAPTCHA响应
  if (!isset($_POST['g-recaptcha-response'])) {
    wp_redirect(add_query_arg('reg_error', '请完成人机验证', $_SERVER['HTTP_REFERER']));
    exit;
  }

  $verify_response = wp_remote_post('https://www.google.com/recaptcha/api/siteverify', [
    'body' => [
      'secret' => '你的Secret Key',
      'response' => $_POST['g-recaptcha-response'],
      'remoteip' => $_SERVER['REMOTE_ADDR']
    ]
  ]);

  if (is_wp_error($verify_response)) {
    wp_redirect(add_query_arg('reg_error', '验证失败，请重试', $_SERVER['HTTP_REFERER']));
    exit;
  }

  $verify_result = json_decode(wp_remote_retrieve_body($verify_response), true);
  if (!$verify_result['success']) {
    wp_redirect(add_query_arg('reg_error', '人机验证未通过', $_SERVER['HTTP_REFERER']));
    exit;
  }

  // 原有注册逻辑（字段验证、创建用户等）
  $username = sanitize_user($_POST['username'] ?? '');
  $email = sanitize_email($_POST['email'] ?? '');
  
  if (empty($username) || empty($email)) {
    wp_redirect(add_query_arg('reg_error', '请填写必填字段', $_SERVER['HTTP_REFERER']));
    exit;
  }

  $user_id = wp_create_user($username, wp_generate_password(), $email);
  if (is_wp_error($user_id)) {
    wp_redirect(add_query_arg('reg_error', $user_id->get_error_message(), $_SERVER['HTTP_REFERER']));
    exit;
  }

  // 注册成功跳转
  wp_redirect(add_query_arg('reg_success', '1', $_SERVER['HTTP_REFERER']));
  exit;
}

核心注意点：

• 表单的action必须用admin_url('admin-post.php')动态生成，不要硬编码域名
• 处理函数末尾必须加exit，避免WordPress额外输出导致空白
• 所有错误分支都要做跳转，不能只抛出错误不处理

如果reCAPTCHA集成仍有问题，试试这些轻量方案：

• 强化蜜罐字段：用CSS把一个看似正常的字段（比如name="website"）移到视窗外，后台检查该字段是否为空，不为空直接拦截
• 时间差验证：表单加载时生成时间戳存在隐藏字段，后台计算提交时间差，小于2秒的判定为机器人提交
• 随机算术题：动态生成简单算术题（比如<?php $a=rand(1,5); $b=rand(1,5); echo "$a+$b=?"; ?>），后台验证答案，避免固定答案被破解
• IP频率限制：用set_transient存储IP的提交次数，1小时内超过3次就拦截
• 添加nonce验证：给表单加防CSRF的nonce字段，同时增加垃圾注册难度：

<?php wp_nonce_field('custom_reg_nonce', 'reg_nonce'); ?>

后台验证：

if (!isset($_POST['reg_nonce']) || !wp_verify_nonce($_POST['reg_nonce'], 'custom_reg_nonce')) {
  wp_redirect(add_query_arg('reg_error', '请求无效', $_SERVER['HTTP_REFERER']));
  exit;
}

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