后端 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。
基于分数的推荐动作
高分(> 0.5):立即授予访问权限。
低分(< 0.5):不要只是一味拦截。相反,应引入摩擦:
实施检查清单
注册 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。
实用链接