reCAPTCHA v3 实现笔记

一、概述

reCAPTCHA v3 是一种用于区分用户和机器人行为的安全验证服务。它通过在后台评估用户行为并返回一个分数来判断用户是否为真实用户。本文将介绍如何在前端和后端实现 reCAPTCHA v3 的集成。

二、注册和密钥生成

1. 注册 reCAPTCHA v3

   • 访问 Google reCAPTCHA 管理页面（需确保链接合法且网络正常）。
   • 如果链接无法访问，请检查链接的合法性或稍后重试。
   • 注册时需要填写网站信息，并选择 reCAPTCHA v3。
   • 注册完成后，Google 会生成一对密钥：
     • 前端密钥（Site Key）：用于前端页面。
     • 后端密钥（Secret Key）：用于后端验证。

2. 密钥示例

   • 前端密钥：4LfczOEqAAAAAK9B4aegJ3McvFYjCra0GSEHSVI9（请替换为实际生成的密钥）
   • 后端密钥：4LfczOEqAAAAALFmTHfxHimHV35T8C0FuRXN26Un（请替换为实际生成的密钥）

三、前端实现

1. 引入 reCAPTCHA 脚本
   在 HTML 文件中，添加以下脚本以加载 reCAPTCHA v3：

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

2. 执行 reCAPTCHA
   在页面加载完成后，调用 grecaptcha.execute 方法生成验证令牌：

   window.grecaptcha.ready(() => {
       window.grecaptcha.execute('Site_Key', { action: 'submit' }).then((token) => {
           console.log(token); // 获取到的验证令牌
           // 将令牌发送到后端进行验证
           request('backend_api_url', { recaptcha: token }).then((res) => console.log(res));
       });
   });
   

   • 注意：
     • action 参数用于指定用户行为的类型（如 submit）。
     • 生成的 token 需要发送到后端进行验证。

四、后端实现

1. 安装依赖
   确保安装了 axios：

   npm install axios
   

2. 验证 reCAPTCHA
   后端代码如下：

   import axios from "axios";
   
   interface RecaptchaRequest {
       secret?: string;
       response: string;
       remoteip?: string;
   }
   
   async function verifyRecaptcha(requestData: RecaptchaRequest): Promise<any> {
       requestData.secret = "Secret_Key"; // 替换为实际的后端密钥
       console.log("🚀 ~ verifyRecaptcha ~ requestData:", requestData);
   
       try {
           const url = "https://www.google.com/recaptcha/api/siteverify";
           const params = new URLSearchParams();
           params.append('secret', requestData.secret);
           params.append('response', requestData.response);
           if (requestData.remoteip) {
               params.append('remoteip', requestData.remoteip);
           }
   
           const response = await axios.post(url, params);
   
           return response.data;
       } catch (error) {
           console.error("Error verifying reCAPTCHA:", error);
           throw error;
       }
   }
   
   export default verifyRecaptcha;
   

3. 返回结果示例
   验证成功后，Google 返回的结果如下：

   {
       "action": "submit",
       "challenge_ts": "2025-02-25T07:25:55Z",
       "hostname": "192.168.3.21",
       "score": 0.9,
       "success": true
   }
   

   • success：验证是否成功。
   • score：用户行为的分数（0~1），值越高表示越可能是真实用户。
   • action：与前端传入的 action 参数一致。
   • hostname：请求来源的 IP 地址。

五、注意事项

1. 密钥安全

   • 前端密钥可以公开，但后端密钥必须保密，切勿泄露。
   • 不要将密钥硬编码在代码中，建议使用环境变量管理密钥。

2. 网络问题
   如果在访问 Google reCAPTCHA 管理页面 或其他相关链接时遇到问题，请检查网络连接或链接的合法性。

3. 调试

   • 在开发过程中，建议使用 console.log 或日志工具记录调试信息。
   • 如果后端验证失败，请检查 token 是否正确传递，以及后端密钥是否正确。

六、补充

在前端和后端集成 reCAPTCHA v3，有效防止机器人攻击并保护网站安全。在你的配置管理页面，要把启动v3的网站域名填进去，不然不能生效，后端无法解析前端回传的信息。