测试您的 Turnstile 实施

使用虚拟 (dummy) 的 sitekey 和密匙 (secret key) 来测试您的 Turnstile 实施，而不会触发会干扰自动化测试套件的真实质询。

自动化测试套件（如 Selenium、Cypress 或 Playwright）会被 Turnstile 检测为 bot，这可能会导致：

当 Turnstile 阻止自动化浏览器时，测试会失败
由于质询的变化导致不可预测的测试结果
干扰表单提交测试
难以测试完整的用户流程

虚拟密钥通过提供与自动化测试工具配合使用的、可预测的、受控的响应来解决此问题。

测试 sitekey

Sitekey	行为	小组件类型	用途
`1x00000000000000000000AA`	总是通过	可见	测试表单的成功提交
`2x00000000000000000000AB`	总是失败	可见	测试错误处理和重试逻辑
`1x00000000000000000000BB`	总是通过	不可见	测试不可见小组件的成功流程
`2x00000000000000000000BB`	总是失败	不可见	测试不可见小组件的错误处理
`3x00000000000000000000FF`	强制进行交互式质询	可见	测试用户交互场景

测试密匙 (Test secret keys)

在进行服务器端验证测试时使用这些密匙：

密匙 (Secret key)	行为	用途
`1x0000000000000000000000000000000AA`	总是通过验证	测试成功的令牌验证
`2x0000000000000000000000000000000AA`	总是验证失败	测试验证错误处理
`3x0000000000000000000000000000000AA`	返回“令牌已使用”错误	测试重复令牌处理

实施

本地开发

测试密钥适用于任何域名，包括：

localhost
127.0.0.1
0.0.0.0
任何开发域名

Cloudflare 建议在生产环境中使用的 sitekey 不要允许本地域名（localhost 或 127.0.0.1），但用户可以选择在域名管理 (Hostname Management) 下将本地域名添加到允许的域名列表中。虚拟 sitekey 可以从任何域名使用，包括在 localhost 上。

客户端测试

将您的生产环境 sitekey 替换为测试 sitekey。

<!-- 开发/测试 -->
<div class="cf-turnstile" data-sitekey="1x00000000000000000000AA"></div>

<!-- 生产环境 -->
<div class="cf-turnstile" data-sitekey="your-real-sitekey"></div>

服务器端测试

将您的生产环境密匙替换为测试密匙。

// 基于环境的配置
const SECRET_KEY = process.env.NODE_ENV === 'production' 
  ? process.env.TURNSTILE_SECRET_KEY 
  : '1x0000000000000000000000000000000AA';

// 在验证中使用
const validation = await validateTurnstile(token, SECRET_KEY);

环境配置

为不同的环境设置不同的密钥。

# .env.development
TURNSTILE_SITEKEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

# .env.test  
TURNSTILE_SITEKEY=2x00000000000000000000AB
TURNSTILE_SECRET_KEY=2x0000000000000000000000000000000AA

# .env.production
TURNSTILE_SITEKEY=your-real-sitekey
TURNSTILE_SECRET_KEY=your-real-secret-key

虚拟令牌行为

令牌生成

测试 sitekey 会生成一个虚拟令牌：XXXX.DUMMY.TOKEN.XXXX

令牌验证

测试密匙：仅接受虚拟令牌，拒绝真实令牌。
生产环境密匙：仅接受真实令牌，拒绝虚拟令牌。

验证响应

成功响应json

{
  "success": true,
  "challenge_ts": "2022-02-28T15:14:30.096Z",
  "hostname": "localhost",
  "error-codes": [],
  "action": "test",
  "cdata": "test-data"
}

失败响应json

{
  "success": false,
  "error-codes": ["invalid-input-response"]
}

令牌已被兑现json

{
  "success": false,
  "error-codes": ["timeout-or-duplicate"]
}

测试场景

测试 sitekey	测试密匙	测试用例
`1x00000000000000000000AA`	`1x0000000000000000000000000000000AA`	此组合将始终导致成功的验证。
`2x00000000000000000000AB`	`2x0000000000000000000000000000000AA`	此组合将始终验证失败。
`1x00000000000000000000AA`	`3x0000000000000000000000000000000AA`	此组合将始终因“timeout-or-duplicate”错误而验证失败。