Cloudflare Turnstile
和 CapMonster Cloud

验证码识别、网站安装与测试。

Cloudflare Turnstile解决方案的定价

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

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

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

什么是 Cloudflare Turnstile
什么是 Cloudflare Turnstile
Cloudflare Turnstile 是 Cloudflare 推出的现代验证码,用于保护网站免受自动操作的侵害。对于网站访客而言,验证过程几乎是隐形的,无需完成任务:通常只需单击复选框即可,系统随后决定是否放行或在怀疑是机器人时进行拦截。与 Cloudflare Challenge 不同,Turnstile 验证码直接放置在网站上,而不是在单独的窗口中——通常位于登录或注册表单中。

如何通过 CapMonster Cloud 识别 Cloudflare Turnstile

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

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

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

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

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

创建任务创建任务
arrow
发送 API 请求发送 API 请求
arrow
获取结果获取结果
arrow
将 token 应用到页面将 token 应用到页面
arrow
使用现成库进行 Cloudflare Turnstile 识别
CapMonster Cloud 服务提供了现成的库,方便在 PythonJavaScript (Node.js) 和 C# 中使用。
Python
JavaScript
C#
识别、Token 插入和表单提交
Node.js 示例,展示在您网页上进行验证码识别的完整周期。可能的方法:使用 HTTP 请求获取 HTML 和验证码参数,发送响应并处理结果;或使用自动化工具(如 Playwright)——打开页面,等待验证码,发送参数(测试时可发送正确或错误数据),通过 CapMonster Cloud 客户端获取结果,将 Token 插入表单并查看结果。
python
// npm install playwright @zennolab_com/capmonstercloud-client

import { chromium } from "playwright";
import { CapMonsterCloudClientFactory, ClientOptions, TurnstileRequest } from "@zennolab_com/capmonstercloud-client";

async function main() {
  // 1. 通过 CapMonster Cloud 识别 Turnstile
  const cmcClient = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: 'YOUR_CAPMONSTER_API_KEY' })
  );

  const turnstileRequest = new TurnstileRequest({
    websiteURL: 'http://tsmanaged.zlsupport.com',
    websiteKey: '0x4AAAAAAABUYP0XeMJF0xoy',
  });

  const result = await cmcClient.Solve(turnstileRequest);
  const token = result.solution.token;
  console.log('已接收 Turnstile Token:', token);

  // 2. 启动 Playwright
  const browser = await chromium.launch({ headless: false });
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('http://tsmanaged.zlsupport.com');

  // 3. 填写登录名和密码
  await page.fill('#username', 'your_username');
  await page.fill('#password', 'your_password');

  // 4. 等待隐藏的 Token 字段出现
  await page.waitForSelector('#token', { state: 'attached', timeout: 60000 });

  // 5. 插入 Token 并使字段可见
  await page.evaluate((t) => {
    const tokenInput = document.querySelector('#token');
    if (tokenInput) {
      tokenInput.type = 'text';  // 使字段可见
      tokenInput.value = t;      // 插入 Token
      console.log('Token 已插入 Token 字段');
    } else {
      console.error('未找到字段 #token');
    }
  }, token);

  // 6. 验证 Token 是否实际已插入
  const checkValue = await page.$eval('#token', el => el.value);
  console.log('检查 Token 值:', checkValue);

  // 7. 提交表单
  await page.click('button[type="submit"]');
  console.log('已提交带有 Turnstile Token 的表单');

  // await browser.close();
}

main().catch(err => console.error(err));
如何将 Cloudflare Turnstile 连接到您的网站
为了自信地掌握验证码在您网站上的工作原理,了解其验证逻辑,重新连接或重新配置,建议学习本节。它描述了连接保护的过程——这将帮助您快速了解所有细微差别。

1. 转到 Cloudflare Turnstile 页面,点击 Get Started

2. 注册服务。

3. 在 Turnstile Widgets 中,点击蓝色的 Add Widget 按钮。

HowTo Connect image 1

4. 配置 Cloudflare Turnstile,指定:

  • Widget name—验证码名称(为了方便,例如:登录表单)。
  • Hostname Management—验证码将工作的域名(例如 example.com)。
  • Widget Mode:
    • Managed—最佳选项,验证码自行决定是否显示复选框。
    • Non-interactive—自动执行验证,无需点击。
    • Invisible—完全不可见。
  • Pre-clearance—如果站点通过 Cloudflare 代理(为避免重复验证),请设置为 Yes

5. 创建小部件后,您将收到两个密钥—Site KeySecret Key

HowTo Connect image 2

6. 连接客户端部分

1) 连接 Turnstile 脚本:

自动渲染(页面加载时自动创建小部件):

markup
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

编程控制(通过 JavaScript 自行创建小部件):

markup
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" defer></script>

重要:脚本必须从确切的 URL 加载。代理或缓存可能会导致失败。

2) 为小部件创建容器

自动:

markup
<div class="cf-turnstile" data-sitekey="<YOUR_SITEKEY>"></div>

编程方式:

markup
<div id="turnstile-container"></div>

3) 小部件配置

通过数据属性:

markup
<div class="cf-turnstile"
            data-sitekey="<YOUR_SITEKEY>"
            data-theme="light"
            data-size="normal"
            data-callback="onSuccess">
          </div>

通过 JavaScript:

javascript
const widgetId = turnstile.render("#turnstile-container", {
  sitekey: "<YOUR_SITEKEY>",
  theme: "light",
  size: "normal",
  callback: token => console.log("Token:", token)
});

4) 使用 Token

javascript
const token = turnstile.getResponse(widgetId);      // 获取 Token
const isExpired = turnstile.isExpired(widgetId);    // 检查过期
turnstile.reset(widgetId);                          // 重置
turnstile.remove(widgetId);                         // 移除
turnstile.execute("#turnstile-container");         // 手动执行

5) 与表单集成

markup
<form id="my-form" method="POST">
  <input type="hidden" name="cf-turnstile-response" id="cf-turnstile-response">
  <button type="submit">提交</button>
</form>

<script>
function onSuccess(token) {
  document.getElementById("cf-turnstile-response").value = token;
}
</script>

代码示例代码示例
arrow

6) 配置服务器端部分

服务器端验证流程:

  • 客户端:用户在页面上完成 Turnstile → 创建 Token。
  • 表单提交:Token 与表单数据一起发送到服务器。
  • 服务器:使用 Token 和密钥向 Cloudflare Siteverify API 发送 POST 请求。
  • Cloudflare:返回包含结果 (success: true/false) 和附加信息 (action, hostname, 完成时间) 的 JSON。
  • 服务器:决定允许还是拒绝用户操作。

Siteverify API:

javascript
POST
https://challenges.cloudflare.com/turnstile/v0/siteverify

请求参数:

  • secret (必填):来自 Cloudflare 面板的 Turnstile 密钥
  • response (必填):在客户端接收到的 Token
  • remoteip (可选):用户的 IP 地址(推荐)
  • idempotency_key (可选):用于防止重复验证的唯一 UUID

Token 属性:

  • 最大长度:2048 个字符
  • 有效期 5 分钟
  • 一次性使用
  • 过期或重新验证时,API 将返回 timeout-or-duplicate 错误

PHP 验证示例PHP 验证示例
arrow

Background
可能的错误与调试
Bug Icon
参数不正确
验证码未显示或返回错误,如 invalid-input-secretmissing-input-responseinvalid-input-response。请检查 sitekeysecret key 的有效性,以及 Cloudflare Dashboard 中的设置。
Bug Icon
识别超时
Token 已过期(有效期 300 秒)或未及时收到。请确保连接稳定且 API 集成正确。
Bug Icon
Token 为空或不正确
缺少参数 cf-turnstile-response 或参数不正确。请检查 Token 到表单和服务器的传输。
Bug Icon
响应 success=false
Token 无效、已过期或已被使用。每个 Token 只能验证一次。启用 Siteverify 请求和响应的日志记录以进行分析。
验证防护的可靠性
集成完成后,务必确认系统确实能够抵御自动化行为。
安全与优化建议
仅在服务器端验证 Token,切勿从前端调用 Siteverify API——这会泄露您的密钥。
使用环境变量或密钥管理系统,而不是将密钥存储在代码中。
检查附加字段(<span class="font-bold">hostname</span>、<span class="font-bold">action</span>),以确保请求来自您的网站。
使用 HTTPS——所有对 Siteverify 的调用都应通过安全连接进行。
实施错误处理——当 API 不可用时,向用户显示清晰的消息,而不泄露内部数据。
按域名限制 sitekey 的使用。
如果您的组织或隐私政策有要求,请将<span class="font-bold">隐私政策</span>和<span class="font-bold">Cloudflare 服务条款</span>的链接添加到表单中。
结论

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

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

Conclusion

关于 Cloudflare Turnstile 的常见问题

使用 CapMonster Cloud 解决 Cloudflare Turnstile:

https://api.capmonster.cloud/createTask 发送 POST 请求,包含以下 JSON 参数:

json
{
  "clientKey": "API_KEY",
  "task": {
    "type": "TurnstileTask",
    "websiteURL": "[page_URL_with_Turnstile]",
    "websiteKey": "[Turnstile_website_key]"
  }
}
  • clientKey:您的 CapMonster Cloud API 密钥
  • task.type:TurnstileTask
  • task.websiteURL:解决验证码的页面 URL
  • task.websiteKey:Turnstile site key。查看如何获取。

API 返回 taskId。

使用 clientKey 和 taskId 轮询 https://api.capmonster.cloud/getTaskResult,直到响应状态变为 ready

任务完成后,响应包含 token 和匹配的 userAgent

将两个值传递给将提交表单的同一浏览器会话。

详情请参阅 Turnstile 任务文档

Cloudflare Turnstile 支持三种 widget 模式:

  • Managed:Turnstile 根据风险决定显示交互式验证还是静默放行访客。
  • Non-interactive:无需用户交互即可运行,但在检查期间仍显示可见的 widget。
  • Invisible:同样无需用户交互,但 widget 不向访客显示。

当后端从客户端收到 Turnstile token 后:

通过 POST 将其发送到 https://challenges.cloudflare.com/turnstile/v0/siteverify,参数包括:

  • secret:来自 Cloudflare 控制面板的 widget 密钥
  • response:来自客户端 widget 的 token
  • remoteip(可选):访客的 IP 地址
  • idempotency_key(可选):您生成的 UUID,用于安全重试验证

该端点同时接受 application/x-www-form-urlencodedapplication/json

如果 token 验证成功,Cloudflare 返回 success: true

在提交表单前,使用 page.evaluate() 或其他 DOM 级方法将 token 注入到 [name="cf-turnstile-response"] 字段中。

请注意,某些集成还依赖回调或自定义 JavaScript 处理程序。此时请调用 widget 的 JS 回调函数(在 data-callback 中定义),并将收到的 token 传递给服务器验证。

Turnstile siteverify 返回的 timeout-or-duplicate 错误通常表示 token 在验证前已过期或被多次提交。Turnstile token 为一次性使用,五分钟后过期。

调试错误时: