WordPress全站CAPTCHA强制验证与定时豁免实现指南

1. 理解全站CAPTCHA验证的需求与挑战

在wordpress网站上实现全站（即访问任何页面前）的captcha验证，并带有时间豁免机制，是一个常见的安全需求，尤其适用于需要高度控制访问的场景。用户通常希望：

• 全站拦截： 访客在看到任何内容前必须先通过CAPTCHA。
• 定时豁免： 一旦通过验证，在指定时间内（如6小时）无需重复验证。
• WordPress兼容： 解决方案需与WordPress环境无缝集成。
• SEO考量： 即使影响搜索引擎抓取也在可接受范围内。

传统的插件或简单地在页眉页脚插入HTML代码可能难以实现这种全站、持续且带有豁免逻辑的复杂拦截。这需要更深入的前端控制和后端验证机制。

2. 核心技术选型：Google reCAPTCHA v2

Google reCAPTCHA v2（"我不是机器人"复选框）是实现此类验证的理想选择，因为它用户体验友好且具有强大的机器人识别能力。

2.1 获取Site Key和Secret Key 在开始之前，您需要在Google reCAPTCHA官网（g.co/recaptcha/admin）注册您的网站，并获取以下两个关键信息：

• Site Key (网站密钥)： 用于前端渲染CAPTCHA。
• Secret Key (秘密密钥)： 用于后端验证CAPTCHA响应。

3. 客户端实现：前端拦截、reCAPTCHA渲染与豁免逻辑

客户端的实现是整个方案的核心，它负责在访客看到内容前拦截页面，显示CAPTCHA，并在验证通过后解除拦截并设置豁免Cookie。

3.1 页面内容隐藏机制 为了实现全站拦截，我们需要在页面加载时默认隐藏所有内容，只显示一个CAPTCHA容器。

    
请验证您不是机器人以继续访问
    




    
    
        
    

上述HTML结构中，#captcha-overlay 默认显示，覆盖整个页面，而 #site-content 默认隐藏。

3.2 reCAPTCHA加载与渲染 为了确保reCAPTCHA的API脚本加载和渲染回调函数的正确执行，尤其是在异步加载或复杂脚本环境中，我们需要一个健壮的grecaptcha.ready处理机制。

首先，引入reCAPTCHA API脚本：

然后，使用以下JavaScript代码来处理grecaptcha.ready，并渲染CAPTCHA：

代码说明：

• grecaptcha.ready的重写确保了grecaptcha.render能在API加载完成后被调用，增强了代码的鲁棒性。
• onRecaptchaSuccess是CAPTCHA验证成功后的回调函数。它负责将CAPTCHA响应令牌（token）发送到服务器进行验证。
• 如果服务器验证成功，页面内容被显示，并设置一个名为recaptcha_passed的Cookie，有效期为6小时。
• 页面加载时，首先检查recaptcha_passed Cookie。如果存在且未过期，则直接显示网站内容；否则，显示CAPTCHA。

4. 服务器端验证：关键的安全保障

重要提示： 客户端的CAPTCHA验证结果是不可信的。恶意用户可以绕过前端验证。因此，务必在服务器端对CAPTCHA响应令牌进行验证。

火山写作

字节跳动推出的中英文AI写作、语法纠错、智能润色工具，是一款集成创作、润色、纠错、改写、翻译等能力的中英文 AI 写作助手。

下载

4.1 验证流程

1. 客户端通过AJAX将g-recaptcha-response令牌发送到服务器。
2. 服务器接收到令牌后，向Google reCAPTCHA验证API发送POST请求：
   • URL: https://www.google.com/recaptcha/api/siteverify
   • 参数:
     • secret: 您的Google reCAPTCHA Secret Key。
     • response: 客户端发送的g-recaptcha-response令牌。
     • remoteip (可选): 用户的IP地址。
3. Google API返回JSON响应，指示验证是否成功（"success": true）。
4. 服务器根据响应结果，决定是否返回成功状态给客户端。

4.2 WordPress集成服务器端验证 在WordPress中，您可以通过wp_ajax_和wp_ajax_nopriv_钩子创建一个自定义的AJAX端点来处理服务器端验证。

// 示例：在您的自定义插件或主题的functions.php中
add_action('wp_ajax_verify_recaptcha', 'handle_recaptcha_verification');
add_action('wp_ajax_nopriv_verify_recaptcha', 'handle_recaptcha_verification');

function handle_recaptcha_verification() {
    $response_token = isset($_POST['token']) ? sanitize_text_field($_POST['token']) : '';
    $secret_key = 'YOUR_SECRET_KEY'; // 替换为您的 Secret Key

    if (empty($response_token)) {
        wp_send_json_error(['message' => 'CAPTCHA token missing.']);
    }

    $verify_url = 'https://www.google.com/recaptcha/api/siteverify';
    $request_args = array(
        'body' => array(
            'secret' => $secret_key,
            'response' => $response_token,
            'remoteip' => $_SERVER['REMOTE_ADDR'] // 可选
        )
    );

    $response = wp_remote_post($verify_url, $request_args);

    if (is_wp_error($response)) {
        wp_send_json_error(['message' => 'Failed to connect to reCAPTCHA API.']);
    }

    $body = wp_remote_retrieve_body($response);
    $data = json_decode($body, true);

    if (isset($data['success']) && $data['success'] === true) {
        wp_send_json_success(['message' => 'CAPTCHA verified successfully.']);
    } else {
        // 可以根据 $data['error-codes'] 提供更详细的错误信息
        wp_send_json_error(['message' => 'CAPTCHA verification failed.', 'errors' => $data['error-codes'] ?? []]);
    }

    wp_die(); // 终止后续执行
}

5. WordPress集成策略

为了将上述HTML、CSS和JavaScript代码以及PHP后端逻辑集成到WordPress中，推荐使用以下方法：

5.1 方法一：创建自定义WordPress插件（推荐） 这是最健壮和可维护的方案。

1. 创建插件文件夹和主文件： 在wp-content/plugins/下创建一个新文件夹（如site-wide-captcha），并在其中创建一个PHP文件（如site-wide-captcha.php）。

2. 插件头部信息： 在PHP文件顶部添加标准的WordPress插件头部注释。

3. Enqueuing Scripts and Styles： 使用wp_enqueue_scripts钩子加载您的CSS和JavaScript文件。

   function swc_enqueue_scripts() {
       // 注册并加载reCAPTCHA API
       wp_enqueue_script('google-recaptcha-api', 'https://www.google.com/recaptcha/api.js', array(), null, true);
   
       // 注册并加载您的自定义JS
       wp_enqueue_script('swc-custom-captcha-script', plugin_dir_url(__FILE__) . 'js/custom-captcha.js', array('google-recaptcha-api'), '1.0', true);
   
       // 将 PHP 变量传递给 JavaScript (例如 AJAX URL 和 Site Key)
       wp_localize_script('swc-custom-captcha-script', 'swc_ajax_object', array(
           'ajax_url' => admin_url('admin-ajax.php'),
           'site_key' => 'YOUR_SITE_KEY' // 替换为您的 Site Key
       ));
   
       // 注册并加载您的自定义CSS
       wp_enqueue_style('swc-custom-captcha-style', plugin_dir_url(__FILE__) . 'css/custom-captcha.css', array(), '1.0');
   }
   add_action('wp_enqueue_scripts', 'swc_enqueue_scripts');

   • 将前端JavaScript代码放入js/custom-captcha.js文件，并将YOUR_SITE_KEY替换为swc_ajax_object.site_key。
   • 将CSS代码放入css/custom-captcha.css文件。

4. 插入HTML结构： 使用wp_body_open或wp_footer钩子在页面加载时插入CAPTCHA的HTML结构。

   function swc_add_captcha_overlay() {
       echo '
       
   
           
   请验证您不是机器人以继续访问
           
   
       
       
   
       ';
   }
   add_action('wp_body_open', 'swc_add_captcha_overlay'); // 确保在内容之前
   // 或者，如果主题不支持 wp_body_open，可以在主题的 header.php 中手动插入
   
   function swc_close_site_content_div() {