WordPress自定义表单集成Google reCAPTCHA v3失败求助

问题背景 #

运行WordPress站点，为自定义联系表单添加Google reCAPTCHA v3防护，前端能正常获取g-recaptcha-response token，但后端验证始终返回false，怀疑file_get_contents无法正常工作，不想使用插件。

解决方案 #

1. 替换file_get_contents为cURL #

多数服务器会限制file_get_contents访问外部HTTPS资源，改用cURL兼容性更强、可靠性更高。修改后端验证代码如下：

// reCAPTCHA v3
define('SECRET_KEY', '你的实际密钥');

// 检查是否收到reCAPTCHA响应
if (!isset($_POST['g-recaptcha-response'])) {
    die('缺少reCAPTCHA验证信息');
}

$recaptcha_response = $_POST['g-recaptcha-response'];

// 初始化cURL请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.google.com/recaptcha/api/siteverify');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'secret' => SECRET_KEY,
    'response' => $recaptcha_response,
    'remoteip' => $_SERVER['REMOTE_ADDR'] // 可选，提升验证准确性
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // 强制SSL验证，避免安全风险

$Response = curl_exec($ch);
$curl_error = curl_error($ch);
curl_close($ch);

// 检查cURL请求是否失败
if ($curl_error) {
    die('验证请求失败：' . $curl_error);
}

$Return = json_decode($Response);

if ($Return && $Return->success && $Return->score > 0.5) {
    // 执行邮件发送逻辑
    echo '验证通过，邮件已发送';
} else {
    // 输出错误信息用于排查
    echo '验证失败：';
    print_r($Return->{'error-codes'} ?? '未知错误');
}

2. 确保密钥完全一致 #

• 后端SECRET_KEY必须和Google reCAPTCHA控制台生成的密钥完全匹配，无拼写错误、空格或多余字符；
• 前端脚本中的密钥不要硬编码，改为调用PHP定义的SITE_KEY，避免前后端不一致：

<script>
grecaptcha.ready(function() {
  grecaptcha.execute("<?php echo SITE_KEY; ?>", {action: "homepage"})
  .then(function(token) {
    console.log(token);
    document.getElementById("g-recaptcha-response").value=token;
  });
});
</script>

3. 检查Google控制台配置 #

• 确认在Google reCAPTCHA控制台中已正确添加站点域名（包含www和非www版本，若适用）；
• 确认选择的reCAPTCHA类型为v3，而非v2。

4. 添加调试日志排查问题 #

在后端代码中添加日志输出，查看具体错误原因（调试完成后记得删除，避免敏感信息泄露）：

// 记录原始响应和解析结果到日志文件
file_put_contents(WP_CONTENT_DIR . '/recaptcha_debug.log', $Response . PHP_EOL, FILE_APPEND);
file_put_contents(WP_CONTENT_DIR . '/recaptcha_debug.log', print_r($Return, true) . PHP_EOL, FILE_APPEND);

5. WordPress环境最佳实践 #

不要使用独立PHP文件处理表单提交，建议利用WordPress的admin_post钩子，避免权限和环境变量问题：

1. 在主题functions.php中添加处理函数：

add_action('admin_post_submit_footer_form', 'handle_footer_form_submission');
add_action('admin_post_nopriv_submit_footer_form', 'handle_footer_form_submission');

function handle_footer_form_submission() {
    // 此处放置reCAPTCHA验证和邮件发送代码
    // 验证完成后跳转回表单页面或结果页
    wp_redirect(get_home_url() . '/form-result');
    exit;
}

2. 修改表单action属性：

<form action="<?php echo admin_url('admin-post.php'); ?>" method="POST" id="footer-form">
    <input type="hidden" name="action" value="submit_footer_form">
    <!-- 其他表单字段及reCAPTCHA隐藏域 -->
</form>

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