reCAPTCHA v3
与 CapMonster Cloud

验证码解决方案、网站集成与测试。

reCAPTCHA v3解决方案的定价

验证码
价格 (USD)
$ 0.90
1000 代币
接手一个已经部署 captcha 或其他防护的站点,却无法访问源代码?此时最关心的是使用了哪种方案、配置是否正确以及如何测试。

在本文中,我们尽量回答了所有关键问题。要开始解决问题,第一步是确定当前使用的是哪种防护系统。为此,您可以查看常见验证码与反机器人防护系统列表,其中提供了可视化示例和关键特征,帮助您快速判断自己正在使用哪一种方案。

如果您发现自己的网站使用的是 reCAPTCHA v3,下一步就是更深入地了解它的特性和具体工作方式。在本文中,您还可以查看 reCAPTCHA v3 的接入说明,以便彻底弄清它在您的网站上是如何运行的。这样一来,您不仅能更好地理解当前的防护机制,还可以更合理地规划后续的维护和支持。

什么是 Google reCAPTCHA v3
什么是 Google reCAPTCHA v3
reCAPTCHA v3 是 Google 提供的一种不可见防护机制,可以在无需勾选“我不是机器人”的情况下区分真实用户和机器人。页面上会运行一个隐藏脚本,分析访问者的行为,并给出从 0.0 到 1.0 的 信任评分(score)。开发者可以设置一个阈值,当评分低于该阈值时,触发额外验证或直接拦截,从而在不增加用户操作的前提下提高安全性。

如何通过 CapMonster Cloud 解决 reCAPTCHA v3

测试包含 reCAPTCHA v3 的表单时,常常需要确认 captcha 是否集成正确并工作正常。

你可以手动验证站点上的 captcha。

  • 打开表单页面,确认 captcha 能够显示。
  • 尝试在不解题的情况下提交——服务器应返回错误。
  • 解题成功后,表单应顺利提交。

若想自动解题,可以使用 CapMonster Cloud 等服务,它会接收验证码参数、在服务器中解析并返回可直接使用的 token。把 token 注入表单即可无需人工操作通过验证。

通过 CapMonster Cloud API 工作的一般流程:

创建任务创建任务
arrow
发送 API 请求发送 API 请求
arrow
获取结果获取结果
arrow
将 token 应用到页面将 token 应用到页面
arrow
使用现成库识别 reCAPTCHA v3
CapMonster Cloud 提供了适用于 PythonJavaScript(Node.js)和 C# 的现成库,便于集成使用。
Python
JavaScript
C#
解决、填充令牌并提交表单的完整流程
这里展示了一个在 Node.js 中完成整套验证码识别流程的示例。可以采用的方式包括:通过 HTTP 请求获取页面 HTML 和验证码参数,发送解答并处理结果;或者借助自动化工具(例如 Playwright)——打开页面,等待验证码加载,发送参数(在测试时既可以发送正确数据,也可以发送错误数据),然后通过 CapMonster Cloud 客户端获取结果,将令牌填入表单并查看最终响应。
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'; // 带有验证码的页面 URL
  const SITE_KEY = '6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob';
  const API_KEY = 'your_capmonster_cloud_api_key'; // 填写你的 CapMonster Cloud API 密钥

  // 创建 CapMonster 客户端
  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' });

  // 配置 reCAPTCHA v3 任务
  const recaptchaRequest = new RecaptchaV3ProxylessRequest({
    websiteURL: TARGET_URL,
    websiteKey: SITE_KEY,
    minScore: 0.6,
    pageAction: 'myverify', // 确保与页面上的 action 一致
  });

  // 解决验证码
  const solution = await cmcClient.Solve(recaptchaRequest);
  const token = solution.solution?.gRecaptchaResponse;

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

  console.log('已获取令牌:', 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();
  }, token);

  console.log('令牌已插入,表单已提交');

  await page.waitForTimeout(5000);
  await browser.close();
})();
如何将 reCAPTCHA v3 接入自己的网站
为了更好地理解站点上验证码的工作方式、验证逻辑以及如何重新接入或重新配置,我们建议先阅读本章节。这里详细说明了接入防护的整个流程,帮助你快速掌握所有细节。

1. 打开 reCAPTCHA 的管理控制台页面。

2. 注册一个新站点,并选择验证码类型为 reCAPTCHA v3

HowTo Connect image 1

3. 获取两组密钥:

  • Site key — 公钥(在前端页面中使用);
  • Secret key — 私钥(在服务器端用于验证)。

HowTo Connect image 2

在设置中,你还可以补充配置允许使用 reCAPTCHA 的域名,以及当站点出现问题或可疑流量增长时的告警通知。

4. 前端集成代码示例

使用 reCAPTCHA v3 最简单的方式,是引入 JavaScript API 并在按钮上添加相应属性。

引入 API:

<script src="https://www.google.com/recaptcha/api.js"></script>

表单的回调函数:

<script>
  function onSubmit(token) {
    document.getElementById("form").submit();
  }
</script>

带有 reCAPTCHA 属性的按钮:

<button class="g-recaptcha" 
        data-sitekey="reCAPTCHA_sitekey" 
        data-callback='onSubmit' 
        data-action='submit'>Submit</button>

如果需要更精细的控制,可以使用带有 render 参数的 grecaptcha.execute

携带站点密钥引入 API:

<script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script>

以代码方式调用:

<script>
  function onClick(e) {
    e.preventDefault();
    grecaptcha.ready(function() {
      grecaptcha.execute('reCAPTCHA_sitekey', {action: 'submit'}).then(function(token) {
          // 将令牌发送到服务器进行验证
      });
    });
  }
</script>

令牌应立即发送到服务器进行校验。

重要说明:

  • 令牌有效期:reCAPTCHA v3 返回的令牌仅在 2 分钟内有效,请确保在此时间内将其发送到服务器。
  • 服务器端校验:服务器拿到令牌后,需要向 https://www.google.com/recaptcha/api/siteverify 发送 POST 请求,参数包括:
    – secret:你的密钥
    – response:从客户端收到的令牌
    – remoteip(可选):用户的 IP 地址
  • Google 服务器会返回一个 JSON 响应,其中包含校验结果的详细信息。

5. 接下来在服务器端验证响应

PHP 示例PHP 示例
arrow

说明:

  • 请确保在客户端中,将令牌通过名为 recaptcha-token 的隐藏表单字段发送到服务器:
    • <input type="hidden" name="recaptcha-token" id="recaptcha-token">

      • 可以根据所需的严格程度调整 score 阈值(例如 0.3–0.7)。
      • 额外校验 action === 'submit' 能提高安全性,确保令牌对应的是页面上的特定操作。
Background
可能的错误与调试
Bug Icon
站点或密钥不正确
验证码未加载,或者返回 invalid-input-secret 错误。
Bug Icon
解决超时
服务器在等待结果时超时,请增加等待时间.
Bug Icon
令牌为空
将结果传递到页面时出现错误。
Bug Icon
返回 success=false
令牌已过期、被重复使用或遭到篡改。为便于排查,请开启请求日志,并检查 Google 返回结果中的 error-codes 字段。
Bug Icon
评分过低(例如 <0.5)
即使 success=true,评分过低也可能导致拒绝,因为 Google 会根据评分评估用户可信度。
Bug Icon
请检查 action
以确保该令牌确实是为页面上的特定操作生成的
验证防护的可靠性
集成完成后,务必确认系统确实能够抵御自动化行为。
安全与优化建议
<span class="font-bold">Secret Key</span> 只能保存在服务器端,不要暴露在客户端。
记录错误代码(<span class="font-bold">error-codes</span>)和<span class="font-bold">score</span>值,以便了解被拒原因。
在 Google 的响应中<span class="font-bold">检查 action 字段</span>,以确认令牌对应的是页面上期望的操作。
按照许可要求,在表单底部添加指向<span class="font-bold">隐私政策</span>和<span class="font-bold">Google 使用条款</span>的链接。
结论

如果你接手了一个已经集成了验证码或其他防护系统的网站,但又无法访问其代码,也不用担心!要判断实际使用了哪种技术其实并不难。为了核实其是否正常工作,你可以在隔离的测试环境中使用CapMonster Cloud识别服务,确保令牌处理机制和校验逻辑都运行正常。

对于reCAPTCHA v3,只需识别出所用的系统,观察其行为,并确认防护是否正常工作即可。本文演示了如何识别 reCAPTCHA v3,以及到哪里查找其接入或重新配置的说明文档,从而帮助你自信地维护防护方案并掌控其运行情况。

Conclusion

关于 reCAPTCHA v3 的常见问题

CapMonster Cloud 为 Python、JavaScript(Node.js)和 C# 提供官方客户端库。这些库简化了 reCAPTCHA v3 的集成,无需手动实现 HTTP 请求。

例如,在 Node.js 中可以使用 @zennolab_com/capmonstercloud-client 包,只需几行代码即可获取 token 并注入表单。

如果没有针对您语言的专用库,请使用通用 REST API(createTask / getTaskResult)。它适用于任何 HTTP 客户端,包括 curl、requests、axios 等。

完整的请求结构请参阅 API 文档

minScore 参数接受 0.1 到 0.9 的值,用于告知 CapMonster Cloud 返回的 token 必须达到的最低信任分数。0.7 是合理的起点。设置过高(如 0.9)会增加求解失败的几率;设置过低可能返回服务器端阈值本应拒绝的低分 token。请根据测试环境中的实际拒绝率调整该值。

从 reCAPTCHA v3 获取的 token 有效期约为 2 分钟。自动化流程必须在此窗口内将 token 提交到服务器;过期后,Google 的 siteverify 端点将返回 success: false。尽量在表单提交前立即完成求解步骤,避免在请求之间缓存 token。

要注入 reCAPTCHA v3 token,请找到隐藏的响应字段(通常是 ID 为 g-recaptcha-response 的 textarea 或 input),并插入从 CAPTCHA 求解服务获取的 token。以下是三种自动化框架的做法。

Playwright / Puppeteer(Node.js)

const token = "YOUR_TOKEN";
await page.evaluate((t) => {
  document.getElementById('g-recaptcha-response').value = t;
}, token);
await page.click('#submit-btn');

Selenium(Python)

token = "YOUR_TOKEN"
driver.execute_script(f"document.getElementById('g-recaptcha-response').value = '{token}';")
driver.find_element("id", "submit-btn").click()

部分网站使用回调函数验证 token。如果表单未提交,请通过控制台(___grecaptcha_cfg.clients)找到函数名并手动调用:

// Example of calling a callback in Playwright/Puppeteer
await page.evaluate((t) => { window.onSuccessCallback(t); }, token);

Google 返回 success: true 仅表示 token 有效。如果 token 分数低于您配置的阈值,后端仍可能拒绝请求。

另一个常见问题是 action 不匹配。token 必须使用创建任务时相同的 action 值进行验证。

排查步骤:

  • 检查 siteverify 响应中的 score 字段;
  • 确认 action 值一致;
  • 当 success 为 false 时查看 error-codes

若 success 为 true,error-codes 数组通常为空,因此主要应检查 score 和 action 字段。