如何在 React 中实现 reCAPTCHA API：分步指南

请阅读本网站资料的使用条款。

Google 的 reCAPTCHA API 为开发者提供了强大的工具，在保持无缝用户体验的同时保护网站免受垃圾信息和滥用。

本分步指南展示了如何从头到尾完成 reCAPTCHA 的设置。你将了解 reCAPTCHA v2 与 v3 之间的关键差异。指南会带你完成在 Google reCAPTCHA 管理控制台中配置 API 密钥，以及在 React 中添加前端组件的过程。我们还会介绍后端验证步骤。完成之后，你就完全掌握如何通过正确配置的 reCAPTCHA 系统来保护你的 Web 应用。

理解 reCAPTCHA API 与关键概念

理解 reCAPTCHA API 的核心概念以及不同版本，为后续的实现打下坚实基础。Google 提供的这项技术，是帮助网站区分真实用户与自动化机器人（bot）的重要安全层。

Google reCAPTCHA v2 与 v3 概览

Google 主要提供 reCAPTCHA v2 与 v3 两个版本，此外还有用于高级防护的 Enterprise 版本。每个版本的工作方式有所不同：

• reCAPTCHA v2 需要用户直接交互，通过熟悉的“我不是机器人”复选框完成验证。当系统检测到可疑行为时，可能会展示图片选择等可视化挑战，要求用户在图片中识别特定对象。
• reCAPTCHA v3 在后台静默运行，不需要任何用户交互。它不会用挑战打断用户，而是持续监控用户行为，并为每次交互打出风险评分。

这两个版本都需要一对密钥：用于前端实现的站点密钥（site key），以及用于后端验证的私密密钥（secret key）。

reCAPTCHA 如何防护机器人

reCAPTCHA 起到图灵测试的作用，用来区分人类与自动化系统。其防护系统主要包含以下组件：

1. 风险分析引擎：一个高度复杂且可自适应的系统，通过分析用户行为来识别潜在的恶意活动。
2. 基于评分的检测（v3）：v3 会根据用户行为模式打出风险分数，站点所有者可以根据这些分数采取自定义安全策略。
3. 全球情报：系统利用 Google 规模的欺诈情报，从数十亿用户、数百万网站和海量交易中持续学习。

当系统检测到可疑行为时，reCAPTCHA 可能会展示挑战，或直接阻止此次交互。这样既能保护网站安全，又尽量减少对真实用户的干扰。

为你的场景在 reCAPTCHA v2 与 v3 之间做选择

你具体的业务需求应该决定是使用 v2 还是 v3：

在以下情况中选择 v2：

• 你希望有清晰可见的人工验证提示。
• 你的网站需要明确的验证节点（例如表单提交）。
• 你更偏好传统的“挑战–应答”式机制。

在以下情况中选择 v3：

• 你更看重用户体验，希望避免任何打断。
• 你需要详细的风险评分，以支持自定义安全策略。
• 你的网站有多个需要监控的交互点。

你的技术实现能力与安全需求，同样应该在决策时发挥关键作用。

配置 reCAPTCHA API 密钥与基本设置

要开始配置 reCAPTCHA API，你需要先从 Google 获取凭据。下面我们一步步完成站点注册并获取所需密钥。

在 Google reCAPTCHA 管理控制台中注册站点

按以下步骤在 Google reCAPTCHA 管理控制台中注册你的网站：

1. 访问 Google reCAPTCHA Admin Console
2. 使用你的 Google 账号登录。
3. 点击“+”或“Register a new site（注册新站点）”按钮。
4. 填写一个描述性标签，便于你在控制台中识别该站点。
5. 根据你的需求选择合适的 reCAPTCHA 类型（v2 或 v3）。
6. 添加将使用 reCAPTCHA 的域名。
7. 接受服务条款（Terms of Service）。
8. 点击“Submit（提交）”完成注册。

生成 Site Key 与 Secret Key

注册完成后，Google 会为你生成两把密钥：

• Site Key：在前端中使用，用于展示 reCAPTCHA 小部件。
• Secret Key：你的服务器使用它来验证用户响应。

这两把密钥以配对的方式工作来保护你的网站。Site Key 告知 Google 的 reCAPTCHA 服务这是你的哪一个网站；而 Secret Key 则让你的后端可以与 Google 服务器安全通信以验证响应。

使用 .env 文件安全存储 Secret Key

你的 Secret Key 对验证请求至关重要。绝不能将它直接写在源代码里，也不能暴露在客户端代码中。

最好的存储方式是将这些密钥写入 .env 文件中的环境变量：

# .env file
GOOGLE_RECAPTCHA_KEY=your_site_key_here
GOOGLE_RECAPTCHA_SECRET=your_secret_key_here

随后你的应用程序可以通过以下方式访问这些变量：

• 在 Node.js 中：process.env.GOOGLE_RECAPTCHA_KEY
• 在 PHP 中：$_ENV['GOOGLE_RECAPTCHA_KEY']

务必将 .env 文件添加到 .gitignore，以避免不小心将敏感信息提交到代码仓库。

之后你可以随时回到管理控制台，调整域名、安全优先级等设置。

在 React 中集成 reCAPTCHA v2 的前端实现

在获取 API 密钥之后，下一个重要步骤是将 reCAPTCHA v2 集成到你的 React 应用中。前端集成可以让你的网站有效地向用户展示验证挑战。

通过 npm 安装 react-google-recaptcha

你的项目需要一个专门用于 Google reCAPTCHA v2 的 React 组件。请在终端中运行以下命令：

npm install --save react-google-recaptcha

该包提供了一个专门用于集成 reCAPTCHA v2 的 React 组件。

使用 Site Key 渲染 ReCAPTCHA 组件

安装完成后，需要在你的表单文件中引入该组件：

import ReCAPTCHA from "react-google-recaptcha";
import { useRef } from "react";

function ContactForm() {
  const captchaRef = useRef(null);

  return (
    <form>
      {/* Form fields */}
      <ReCAPTCHA
        sitekey={process.env.REACT_APP_SITE_KEY}
        ref={captchaRef}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

组件中的 sitekey 属性会将你的组件与之前生成的 API Key 关联起来。

通过 onChange 回调处理 Token

当验证成功后，reCAPTCHA 会生成一个响应 token，你需要将该 token 发送到后端：

function onChange(value) {
    console.log("Captcha value:", value);
    // Store token or submit form
}

// Add to component props
<
ReCAPTCHA
  sitekey={
    process.env.REACT_APP_SITE_KEY
  }
  onChange={
    onChange
  }
  ref={
    captchaRef
  }
/>

在表单提交时，需要读取并重置 token：

const handleSubmit = (e) => {
  e.preventDefault();
  const token = captchaRef.current.getValue();
  captchaRef.current.reset(); // Reset after use
  // Send token to backend
}

使用 “hl” 参数实现国际化

对于多语言站点，可以通过 hl 属性自定义小部件语言：

<ReCAPTCHA
  sitekey={process.env.REACT_APP_SITE_KEY}
  onChange={onChange}
  hl="fr" // French language
/>

语言代码可以帮助你将小部件渲染为特定语言，从而提升国际用户的体验。

使用 Google reCAPTCHA API 进行后端验证

前端捕获到 token 后，后端必须检查该 reCAPTCHA token 的真实性。这个验证步骤决定用户是否可以继续其预期操作。

向 https://www.google.com/recaptcha/api/siteverify

你的后端需要向 Google 的验证端点发送 POST 请求以检查 token。请求需要包含两个主要参数：

POST 参数：https://www.google.com/recaptcha/api/siteverify

• secret：你的 reCAPTCHA Secret Key
• response：从前端收到的 token
• remoteip：（可选）用户 IP 地址

该端点同时支持 GET 与 POST 请求，但 POST 方式在安全性上更好。

使用 Secret Key 验证 Token

你的 Secret Key 绝不能暴露。最佳实践是将其存储在环境变量中，而不是写死在应用代码里：

// Node.js example
const verifyRecaptcha = async (token) => {
  const response = await fetch('https://www.google.com/recaptcha/api/siteverify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      secret: process.env.RECAPTCHA_SECRET,
      response: token
    }).toString()
  });
  return await response.json();
};

使用 URLSearchParams 可以确保所有参数都被正确进行 URL 编码，避免在处理 token 中的特殊字符时出错。

处理成功与失败响应

API 会返回一个 JSON 对象，其中 v2 与 v3 的结构略有不同。

对于 reCAPTCHA v2：

• success：布尔值，表示验证是否成功。
• challenge_ts：验证时间戳。
• hostname：完成 reCAPTCHA 的网站主机名。
• error-codes：错误信息数组（如有）。

对于 reCAPTCHA v3（在 v2 字段基础上还会包含）：

• score：从 0.0 到 1.0 的数值，表示交互是合法用户的可能性（1.0 表示高度可信）。
• action：生成 token 时指定的操作名称。

v2 响应处理示例：

const result = await verifyRecaptcha(token);
if (result.success) {
  // Proceed with form processing
} else {
  // Handle verification failure
  console.error('Verification failed:', result['error-codes']);
}

v3 带分数校验的响应处理示例：

const result = await verifyRecaptcha(token);
if (result.success && result.score > 0.5 && result.action === 'login') {
  // Proceed with form processing
} else if (result.success && result.score <= 0.5) {
  // Low score - possible bot
  console.warn('Low score detected:', result.score);
} else {
  // Verification failed
  console.error('Verification failed:', result['error-codes']);
}

错误码处理：

返回中的 error-codes 数组可能包含以下值：

• missing-input-secret：缺少 secret 参数。
• invalid-input-secret：secret 参数无效或错误。
• missing-input-response：缺少 response（token）参数。
• invalid-input-response：response 参数无效或已过期。
• bad-request：请求无效或格式错误。
• timeout-or-duplicate：token 已被使用或已过期。

包含 error-codes 的完整处理示例：

const result = await verifyRecaptcha(token);
if (result.success) {
  // Success - proceed with form processing
  return { verified: true };
} else {
  // Handle specific error codes
  const errors = result['error-codes'] || [];
  if (errors.includes('timeout-or-duplicate')) {
    return { verified: false, message: 'Token expired. Please try again.' };
  } else if (errors.includes('invalid-input-response')) {
    return { verified: false, message: 'Invalid verification token.' };
  } else if (errors.includes('missing-input-secret') || errors.includes('invalid-input-secret')) {
    console.error('Server configuration error:', errors);
    return { verified: false, message: 'Server error. Please contact support.' };
  } else {
    return { verified: false, message: 'Verification failed. Please try again.' };
  }
}

Token 过期与一次性使用限制

每个 reCAPTCHA token 的有效期为两分钟，并且只能使用一次。为了改善用户体验，可以采用以下 token 刷新策略：

• 在表单提交前实时生成新的 token。
• 为较长的表单设置自动 token 刷新机制。
• 当 token 过期时展示友好的错误信息。

使用 CapMonster Cloud 测试 reCAPTCHA

CapMonster Cloud 为测试、QA 和开发环境提供自动化的 reCAPTCHA 解决方案。该服务通过 REST API 以编程方式解决 reCAPTCHA v2、v3 以及 Enterprise 版本，并返回你的应用可像真实用户 token 一样使用的 token。

借此，你可以对受保护表单、CI/CD 流水线以及压测场景进行全面测试，而无需人工解题。QA 团队可以在不同场景与分数范围下验证实现效果，开发者则可以测试验证逻辑、错误处理以及 token 过期行为。

CapMonster Cloud 通过简单的 API 调用集成，并支持 Selenium、Puppeteer、Playwright 等流行框架。它可以在开发阶段消除持续出现的 CAPTCHA 阻力，同时验证你的 Google reCAPTCHA 集成，大幅加快上线前的开发周期。

使用 Playwright 和 CapMonster Cloud 的官方 Node.js 库解决 reCAPTCHA v3 的示例

const { chromium } = require('playwright');
const { 
  CapMonsterCloudClientFactory, 
  ClientOptions, 
  RecaptchaV3ProxylessRequest 
} = require('@zennolab_com/capmonstercloud-client');

(async () => {
  const TARGET_URL = 'https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta';
  const SITE_KEY = '6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob';
  const API_KEY = 'your_capmonster_cloud_api_key';

  const cmcClient = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: API_KEY })
  );

  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto(TARGET_URL, { waitUntil: 'domcontentloaded' });

  const recaptchaRequest = new RecaptchaV3ProxylessRequest({
    websiteURL: TARGET_URL,
    websiteKey: SITE_KEY,
    minScore: 0.6,
    pageAction: 'myverify',
  });

  const solution = await cmcClient.Solve(recaptchaRequest);
  const token = solution.solution?.gRecaptchaResponse;

  if (!token) {
    console.error('Token 为空，请检查 sitekey 和 URL');
    await browser.close();
    return;
  }

  console.log('已获取 Token:', token);

  await page.evaluate((t) => {
    const input = document.querySelector('#v3_token');
    if (input) input.value = t;

    const form = document.querySelector('#v3_form');
    if (form) {
      form.submit();
      return;
    }

    if (typeof window.onSubmit === 'function') {
      window.onSubmit(t);
      return;
    }

    if (window.___grecaptcha_cfg) {
      const clients = window.___grecaptcha_cfg.clients;
      for (const clientKey in clients) {
        const client = clients[clientKey];
        for (const prop in client) {
          const cb = client[prop]?.callback;
          if (typeof cb === 'function') {
            cb(t);
            return;
          }
        }
      }
    }

    console.warn('未找到表单或回调函数');
  }, token);

  console.log('Token 已插入，并已调用回调函数（如果可用）');

  await page.waitForTimeout(5000);
  await browser.close();
})();
    

你也可以在我们的网站上查看关于解题、集成与测试验证码的详细说明：

• reCAPTCHA v2
• reCAPTCHA v3
• reCAPTCHA Enterprise
• and other captcha types，了解我们服务支持的其他验证码类型。

结语

Google reCAPTCHA API 能够保护你的网站免受自动化攻击，同时提供更好的用户体验。本文带你从头到尾完成这一安全工具的配置与集成。

了解 reCAPTCHA v2 与 v3 的关键差异，有助于你做出正确选择。V2 使用可见的复选框界面进行验证，而 v3 则在后台静默打分，不打断用户。

正确配置 API 密钥是实现的基础。实践表明，使用环境变量存储 Secret Key 能够提升安全性并保护验证系统的完整性，这些密钥绝不能出现在源代码或代码仓库中。

React 应用需要特定组件来集成 reCAPTCHA。后端验证流程则通过调用 Google 的验证端点完成闭环，对 token 进行校验。

reCAPTCHA 的 token 具有明确限制——有效期为两分钟且仅能使用一次。你需要设计合适的 token 管理策略，以保证流程顺畅。

现在，你已经具备构建稳健 reCAPTCHA 解决方案所需的一切。这种实现方式可以大幅减少你网站上的机器人流量和自动化滥用，同时保持合法用户的顺畅访问体验。这种平衡的安全策略，是在当今充斥机器人的数字世界中部署 reCAPTCHA 技术的理想方式。

实用链接

• https://developers.google.com/recaptcha/intro
• ​https://developers.google.com/search/blog/2018/10/introducing-recaptcha-v3-new-way-to
• https://support.google.com/recaptcha/?hl=en
• https://cloud.google.com/security/products/recaptcha
• https://www.npmjs.com/package/react-google-recaptcha

注意：请注意，该产品旨在用于自动化测试你自己的网站以及你具有合法访问权限的网站。