Google 的 reCAPTCHA API 为开发者提供了强大的工具，在保持无缝用户体验的同时保护网站免受垃圾信息和滥用。
本分步指南展示了如何从头到尾完成 reCAPTCHA 的设置。你将了解 reCAPTCHA v2 与 v3 之间的关键差异。指南会带你完成在 Google reCAPTCHA 管理控制台中配置 API 密钥，以及在 React 中添加前端组件的过程。我们还会介绍后端验证步骤。完成之后，你就完全掌握如何通过正确配置的 reCAPTCHA 系统来保护你的 Web 应用。
理解 reCAPTCHA API 的核心概念以及不同版本，为后续的实现打下坚实基础。Google 提供的这项技术，是帮助网站区分真实用户与自动化机器人（bot）的重要安全层。
Google 主要提供 reCAPTCHA v2 与 v3 两个版本，此外还有用于高级防护的 Enterprise 版本。每个版本的工作方式有所不同：
这两个版本都需要一对密钥：用于前端实现的站点密钥（site key），以及用于后端验证的私密密钥（secret key）。
reCAPTCHA 起到图灵测试的作用，用来区分人类与自动化系统。其防护系统主要包含以下组件：
当系统检测到可疑行为时，reCAPTCHA 可能会展示挑战，或直接阻止此次交互。这样既能保护网站安全，又尽量减少对真实用户的干扰。
你具体的业务需求应该决定是使用 v2 还是 v3：
在以下情况中选择 v2：
在以下情况中选择 v3：
你的技术实现能力与安全需求，同样应该在决策时发挥关键作用。
要开始配置 reCAPTCHA API，你需要先从 Google 获取凭据。下面我们一步步完成站点注册并获取所需密钥。
按以下步骤在 Google reCAPTCHA 管理控制台中注册你的网站：
注册完成后，Google 会为你生成两把密钥：
这两把密钥以配对的方式工作来保护你的网站。Site Key 告知 Google 的 reCAPTCHA 服务这是你的哪一个网站；而 Secret Key 则让你的后端可以与 Google 服务器安全通信以验证响应。
你的 Secret Key 对验证请求至关重要。绝不能将它直接写在源代码里，也不能暴露在客户端代码中。
最好的存储方式是将这些密钥写入 .env 文件中的环境变量：
# .env file
GOOGLE_RECAPTCHA_KEY=your_site_key_here
GOOGLE_RECAPTCHA_SECRET=your_secret_key_here随后你的应用程序可以通过以下方式访问这些变量：
务必将 .env 文件添加到 .gitignore，以避免不小心将敏感信息提交到代码仓库。
之后你可以随时回到管理控制台，调整域名、安全优先级等设置。
在获取 API 密钥之后，下一个重要步骤是将 reCAPTCHA v2 集成到你的 React 应用中。前端集成可以让你的网站有效地向用户展示验证挑战。
你的项目需要一个专门用于 Google reCAPTCHA v2 的 React 组件。请在终端中运行以下命令：
npm install --save react-google-recaptcha该包提供了一个专门用于集成 reCAPTCHA v2 的 React 组件。
安装完成后，需要在你的表单文件中引入该组件：
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 关联起来。
当验证成功后，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 属性自定义小部件语言：
<ReCAPTCHA
sitekey={process.env.REACT_APP_SITE_KEY}
onChange={onChange}
hl="fr" // French language
/>语言代码可以帮助你将小部件渲染为特定语言，从而提升国际用户的体验。
前端捕获到 token 后，后端必须检查该 reCAPTCHA token 的真实性。这个验证步骤决定用户是否可以继续其预期操作。
你的后端需要向 Google 的验证端点发送 POST 请求以检查 token。请求需要包含两个主要参数：
POST 参数：https://www.google.com/recaptcha/api/siteverify
该端点同时支持 GET 与 POST 请求，但 POST 方式在安全性上更好。
你的 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：
对于 reCAPTCHA v3（在 v2 字段基础上还会包含）：
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 数组可能包含以下值：
包含 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.' };
}
}每个 reCAPTCHA token 的有效期为两分钟，并且只能使用一次。为了改善用户体验，可以采用以下 token 刷新策略：
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 的示例
Google reCAPTCHA API 能够保护你的网站免受自动化攻击，同时提供更好的用户体验。本文带你从头到尾完成这一安全工具的配置与集成。
了解 reCAPTCHA v2 与 v3 的关键差异，有助于你做出正确选择。V2 使用可见的复选框界面进行验证，而 v3 则在后台静默打分，不打断用户。
正确配置 API 密钥是实现的基础。实践表明，使用环境变量存储 Secret Key 能够提升安全性并保护验证系统的完整性，这些密钥绝不能出现在源代码或代码仓库中。
React 应用需要特定组件来集成 reCAPTCHA。后端验证流程则通过调用 Google 的验证端点完成闭环，对 token 进行校验。
reCAPTCHA 的 token 具有明确限制——有效期为两分钟且仅能使用一次。你需要设计合适的 token 管理策略，以保证流程顺畅。
现在，你已经具备构建稳健 reCAPTCHA 解决方案所需的一切。这种实现方式可以大幅减少你网站上的机器人流量和自动化滥用，同时保持合法用户的顺畅访问体验。这种平衡的安全策略，是在当今充斥机器人的数字世界中部署 reCAPTCHA 技术的理想方式。
