如何在 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();
})();
    

结语

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