Captcha API (Google reCAPTCHA v3)：面向开发者的文档与集成指南

请查看本网站所提供内容的使用条款。

本开发者指南记录了 captcha api 在 Google reCAPTCHA v3 中的流程：你的前端获取一个 reCAPTCHA token，你的后端通过 Google 的验证端点对其进行验证。在本文中，“Captcha API”指用于验证 CAPTCHA token 的 CAPTCHA 提供方 API（即 Google 的验证调用）；它不同于“captcha solver API”，后者是另一类尝试进行自动化解题的服务。下文所有内容均基于 Google reCAPTCHA 的官方文档（另包含一个明确标注的侧栏，介绍 solver APIs）。

reCAPTCHA 的工作原理

当你在自己的环境中部署 reCAPTCHA 时，它会与你的后端和客户端（网页或移动应用）进行交互。

当终端用户访问网页或使用移动应用时，会按顺序触发以下事件：

1. 客户端从后端加载网页，或启动移动应用。
2. 网页或移动应用初始化 reCAPTCHA JavaScript API 或移动端 SDK，并开始收集信号。
3. 当终端用户触发由 reCAPTCHA 保护的操作（例如登录）时，客户端中的 reCAPTCHA JavaScript API 或移动端 SDK 会向 reCAPTCHA 请求一个判定结果。
4. reCAPTCHA 将一个加密的 reCAPTCHA token 返回给客户端，以便后续使用。
5. 客户端将加密的 reCAPTCHA token 发送到后端进行评估。
6. 后端将 token 发送到 siteverify REST endpoint。
7. reCAPTCHA 基于对该请求风险的评估结果，向后端返回一个判定结果。该判定结果包含 0.0 到 1.0 的分数以及原因代码。
8. 根据判定结果，你（作为开发者）可以决定针对该特定用户请求或操作应采取的下一步措施。

下面的时序图展示了 reCAPTCHA 工作流的图形化表示：

另请参阅实现工作流图： https://docs.cloud.google.com/recaptcha/docs/implementation-workflow

Captcha API 密钥（site key + secret）

对于 reCAPTCHA v3，你需要在 Google reCAPTCHA Admin Console 中注册密钥，并获取一个 site key（公开）以及一个 secret key（由你的后端使用的共享密钥）。请将 secret 视为你的服务器凭据：它会作为验证端点的 secret 参数被发送，因此绝不能在客户端代码中暴露它。如果你在团队文档中看到诸如 “captcha api key” 或 “api key captcha” 之类的说法，请将它们对应到 reCAPTCHA 的 site key（前端标识符）和 secret key（后端验证凭据）。

客户端集成（JavaScript）

reCAPTCHA v3 在不打断用户的情况下运行，并为每个请求返回一个分数，其中 1.0 更可能是良性交互，0.0 更可能是机器人。你会针对特定 actions（例如 login 或 signup）执行 reCAPTCHA，并且你应该在后端验证返回的 action 是否与你预期一致。Google 建议将 token 与你想要保护的请求一起立即发送到你的后端。

选项 A：绑定到按钮（为 JSON Backend 修改）

加载 JavaScript API，并将 reCAPTCHA 属性附加到一个按钮上。回调函数会接收 token。注意：为了与下方基于 JSON 的后端示例配合使用，该脚本会拦截表单提交，并发送一个 JSON 请求来替代标准的表单提交（form post）。

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
    <script>
     function onSubmit(token) {
       // 阻止默认表单提交并将 JSON 发送到后端
       const form = document.getElementById("demo-form");
       const formData = new FormData(form);
       const data = Object.fromEntries(formData.entries());
       data.recaptchaToken = token; // 将令牌添加到 JSON 有效负载
       fetch("/api/submit", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(data)
       }).then(response => {
         if (response.ok) console.log("Success");
       });
     }
    </script>
    <form id="demo-form">
     <!-- 表单字段 -->
     <button 
       class="g-recaptcha" 
       data-sitekey="YOUR_SITE_KEY" 
       data-callback="onSubmit" 
       data-action="submit" 
       type="button">
       Submit
     </button>
    </form>

选项 B：编程方式执行（推荐用于 APIs/AJAX）

加载带有 api.js 和 ?render=YOUR_SITE_KEY 的脚本，然后针对你想要保护的每个 action 调用 grecaptcha.execute()。

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
    <script>
     async function getTokenAndCallBackend() {
       const token = await new Promise((resolve) => {
         grecaptcha.ready(() => {
           grecaptcha.execute("YOUR_SITE_KEY", { action: "login" }).then(resolve);
         });
       });
       // 向后端发送 POST 令牌，后端将调用 siteverify 函数。
       await fetch("/api/login", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ recaptchaToken: token })
       });
     }
    </script>

Captcha API 验证（REST：siteverify）

Google 的验证 REST endpoint 是 https://www.google.com/recaptcha/api/siteverify，方法为 POST。你需要发送 secret（必填）、 response（客户端提供的 token，必填），以及可选的 remoteip（用户的 IP）。token 具有时间限制和重放限制：每个 token 有效期为两分钟，并且只能验证一次。

REST 请求示例（curl）

curl -X POST \\
 -d "secret=YOUR_SECRET_KEY" \\
 -d "response=USER_TOKEN" \\
 -d "remoteip=USER_IP_OPTIONAL" \\
 https://www.google.com/recaptcha/api/siteverify

REST 响应字段（v3）

成功的响应是一个 JSON 对象，其中包含 success，以及 v3 的字段，例如 score 和 action，并且可能包含 error-codes。你还会看到 challenge_ts（ISO 时间戳）和 hostname（token 被完成验证的主机）。

示例结构（字段会因场景而异）：

{
     "success": true,
     "score": 0.7,
     "action": "login",
     "challenge_ts": "2026-02-18T10:00:00Z",
     "hostname": "example.com"
    }

后端 SDK 风格示例

这些示例做的事情都一样：你的后端接收一个 token，调用携带你的 secret 的 siteverify REST endpoint，然后检查 JSON 响应。对于 reCAPTCHA v3，Google 文档特别指出你应该校验 action，并使用 score 来决定该请求的后续处理方式。

Node.js（服务端验证）

// Node.js 18+
    import express from "express";
    const app = express();
    app.use(express.json()); // Parses application/json requests
    app.post("/api/login", async (req, res) => {
     const token = req.body.recaptchaToken;
     // Prepare parameters for Google (x-www-form-urlencoded)
     const params = new URLSearchParams();
     params.set("secret", process.env.RECAPTCHA_SECRET);
     params.set("response", token);
     const verifyResp = await fetch("https://www.google.com/recaptcha/api/siteverify", {
       method: "POST",
       headers: { "content-type": "application/x-www-form-urlencoded" },
       body: params
     });
     const data = await verifyResp.json();
     if (!data.success) {
       return res.status(403).json({ 
         error: "recaptcha_failed", 
         details: data["error-codes"] 
       });
     }
     if (data.action !== "login") {
       return res.status(403).json({ error: "recaptcha_action_mismatch" });
     }
     // Choose your own thresholds based on traffic patterns
     if (data.score < 0.5) {
       return res.status(403).json({ 
         error: "recaptcha_low_score", 
         score: data.score 
       });
     }
     return res.json({ ok: true });
    });
    app.listen(3000);

 siteverify URL、方法和参数都在 Google 的验证文档中定义。 score 和 action 字段来自 Google 的 reCAPTCHA v3 文档。

Python（服务端验证）

import os
    import requests
    from flask import Flask, request, jsonify
    app = Flask(__name__)
    @app.post("/api/signup")
    def signup():
       token = request.json.get("recaptchaToken")
       r = requests.post(
           "https://www.google.com/recaptcha/api/siteverify",
           data={
               "secret": os.environ["RECAPTCHA_SECRET"],
               "response": token,
               # "remoteip": request.remote_addr,  # optional
           },
           timeout=5,
       )
       data = r.json()
       if not data.get("success", False):
           return jsonify({"error": "recaptcha_failed"}), 403
       if data.get("action") != "signup":
           return jsonify({"error": "recaptcha_action_mismatch"}), 403
       if data.get("score", 0) < 0.5:
           return jsonify({"error": "recaptcha_low_score"}), 403
       return jsonify({"ok": True})

 siteverify endpoint、必需参数以及 error-codes 数组都在 Google 的验证文档中指定。

浏览器端 JavaScript（token 创建回顾）

这是 captcha google api flow 的浏览器端部分：以一个 action 执行 reCAPTCHA，并将 token 转发到你的后端以进行验证。

grecaptcha.ready(() => {
     grecaptcha.execute("YOUR_SITE_KEY", { action: "submit" }).then(async (token) => {
       await fetch("/api/contact", {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ recaptchaToken: token })
       });
     });
    });

认证模型（是什么证明你有权进行验证）

 secret POST 参数是你的网站与 reCAPTCHA 之间的共享密钥，它用于对你发往 siteverify 的服务器到服务器验证调用进行认证。由于 token 很快过期且只能使用一次，你应该及时验证它，并避免使用同一个 token 重试验证。如果你需要一个新 token，Google 的指导是重新运行客户端的 reCAPTCHA 流程。

错误处理与错误码

在 API 层面，验证响应包含 success，并且可能包含用于描述错误原因的 error-codes。Google 针对 siteverify 的已文档化错误码说明如下：

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

将 missing/invalid-* 错误视为配置或请求问题（bug），并将 timeout-or-duplicate 视为一种预期的运行时情况（当 token 过期或被重放时）。

如何解读分数（0.0 到 1.0）

与 reCAPTCHA v2 不同，v3 不会显示挑战（例如“点击公交车”）。相反，它会返回一个分数。

• 1.0：非常可能是良性交互（人类）。
• 0.0：非常可能是机器人。

Google 不会自动拦截请求；如何解读分数取决于你的后端逻辑。一个常见的起始阈值是 0.5。

基于分数的推荐动作

1. 高分（> 0.5）：立即授予访问权限。
2. 低分（< 0.5）：不要只是一味拦截。相反，应引入摩擦：
   • 要求双因素认证（2FA）。
   • 发送验证邮件。
   • 作为回退方案，提供一个可见挑战（例如 reCAPTCHA v2）。
   • 将交易交由人工审核。

实施检查清单

• 注册 reCAPTCHA v3 密钥，并在你的前端集成中嵌入 site key。
• 为明确的 action 名称生成 token，并立即将 token 发送到你的后端。
• 使用你的 secret key 通过 POST https://www.google.com/recaptcha/api/siteverify 验证 token。
• 执行 token 限制：在两分钟内完成验证，并且每个 token 只能验证一次。
• 对于 v3，检查 action 并使用 score 来选择你的响应行为。
• 根据 Google 文档所述含义处理 error-codes（特别是 timeout-or-duplicate）。

Captcha Solver APIs（自动化与测试）

注：本节用于说明引言中提到的 “solver API” 区分。

“Captcha API” 用于保护你的网站，而 Captcha Solver APIs（例如 CapMonster Cloud）是开发者用于自动化测试，或被需要绕过 CAPTCHA 的软件所使用的一类服务。这类服务会使用 AI 或人工来生成可用的 token，以模拟真实用户。

如果你正在构建自动化测试套件或爬虫，并且需要绕过 reCAPTCHA v3，你会使用 solver API 获取一个 token，然后像浏览器一样将其提交到目标网站。

如需更多详情以及 CapMonster Cloud 的集成示例，请参阅其 official API documentation。

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

• reCAPTCHA v2
• reCAPTCHA v3
• reCAPTCHA Enterprise
• 以及其他 captcha 类型，均由我们的服务支持。

实用链接

• https://docs.cloud.google.com/recaptcha/docs
• https://docs.cloud.google.com/recaptcha/docs/overview
• https://developers.google.com/recaptcha/docs/v3
• https://developers.google.com/recaptcha/docs/verify

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