极验v3和v4区别：初始化、参数、二次校验与自动化任务差异

极验v3和v4是两套独立架构

极验第四代（v4）是全新产品，不向下兼容v3的接口和参数。v4移除了请求粘性（Request Stickiness），客户端与服务端可以独立就近请求极验节点，降低延迟并提升容灾能力。开发与自动化测试人员需要按不同版本区分初始化流程、通信参数、服务端校验机制和识别API任务结构。

客户端初始化机制差异

v3初始化流程：宿主站点后端必须先调用极验register接口获取动态challenge和公钥gt，再注入前端：

// v3前端初始化示例
initGeetest({
  gt: "从后端获取的公钥",
  challenge: "从后端获取的动态challenge",
  // 其他配置
}, function (captchaObj) {
  captchaObj.onReady(function () {
    captchaObj.verify();
  });
});

challenge每次会话动态生成，有效期短，过期需重新向业务后端请求。

v4初始化流程：前端无需预先向业务后端请求challenge，直接使用静态公钥captcha_id引入SDK：

// v4前端初始化示例
initGeetest4({
  captchaId: "静态公钥captcha_id",
  product: "bind", // 或 float、popup
}, function (captcha) {
  captcha.onReady(function () {
    captcha.showCaptcha();
  });
});

captcha_id固定，前端可以直接写入配置或环境变量，减少一次后端交互。

极验v3与v4初始化流程对比：v3需后端动态获取challenge，v4前端直接用静态captchaId

验证挑战形态与交互模式差异

v3验证类型：显式交互为主，包括滑块拼图、文字点选、图标点选和空间推理。所有流量都需完成交互验证，无无感通过机制。

v4验证类型：引入自适应模式（Adaptive）：

低风险用户：无感一键通过（OneTap/NoCaptcha），无需任何交互
中风险用户：滑块拼图或文字/图标点选
高风险用户：五子棋（Gobang）、消消乐等复杂交互

极验根据设备特征、行为轨迹和历史记录动态评级，低风险流量可以直接通过，减少正常用户的验证摩擦。

通信参数与加密机制差异

v3通信流程：

前端加载SDK后调用/get.php获取验证配置
用户交互过程中通过/ajax.php提交行为数据
使用RSA与AES结合加密鼠标轨迹、时间戳等生成关键参数w
验证通过后前端生成geetest_challenge、geetest_validate、geetest_seccode三个字段

v4通信流程：

前端直接基于captcha_id加载SDK，请求路径改为/v4/（如gcaptcha4.geetest.com）
收集多维设备特征与行为轨迹生成单一或阶段性w参数
验证通过后前端直接生成四个凭证字段：
- lot_number：流水号，10分钟有效，单次事件唯一
- captcha_output：验证输出摘要
- pass_token：通过凭证
- gen_time：生成时间戳

v4的lot_number是单次事件流水号，有效期固定为10分钟，业务表单提交时必须在有效期内连同其他三个字段一起提交。

服务端二次校验机制差异

v3服务端校验：

接收前端提交的geetest_challenge、geetest_validate、geetest_seccode
使用私钥进行签名比对或调用极验校验接口
返回格式通常为布尔值或状态码

v4服务端校验：

校验接口：gcaptcha4.geetest.com/validate
业务后端必须使用私钥captcha_key对lot_number进行HMAC-SHA256单向散列生成sign_token
连同lot_number、captcha_output、pass_token、gen_time提交校验
返回JSON对象，包含result字段（success/fail）

v4的签名机制从RSA改为HMAC-SHA256，服务端必须在本地计算sign_token，不能直接把captcha_key传给极验。签名逻辑示例（伪代码）：

# v4服务端签名示例（伪代码）
import hmac
import hashlib

captcha_key = "业务私钥"
lot_number = "前端提交的流水号"

sign_token = hmac.new(
    captcha_key.encode(),
    lot_number.encode(),
    hashlib.sha256
).hexdigest()

# 提交sign_token、lot_number、captcha_output、pass_token、gen_time到校验接口

极验v3与v4服务端二次校验机制对比：v3用RSA签名校验validate与seccode，v4用HMAC-SHA256生成sign_token校验lot_number

自动化识别API任务构建差异

在主流验证码识别服务（如2Captcha、CapSolver、NexCaptcha等）中，v3和v4任务类型完全不同。

v3任务必须动态提取challenge：

任务类型：GeeTestTaskProxyless 或 GeeTestTask
必须参数：gt（公钥）、challenge（动态会话标识）、目标网址
challenge每次会话变化，自动化脚本需要先访问宿主页面或模拟业务后端register接口提取当前challenge
识别成功返回：validate、seccode等字段，注入表单后提交

v4任务只需静态captcha_id：

任务类型：GeeTestV4TaskProxyless 或 GeeTestV4Task
必须参数：captchaId（静态公钥）、目标网址
可选参数：riskType（验证风险类型，如slide、icon、gobang等）
识别成功返回：lot_number、pass_token、gen_time、captcha_output，直接注入表单提交

captcha_id固定不变，自动化脚本可以写入配置文件，无需每次会话动态提取，减少一次HTTP请求和解析步骤。

通用REST任务提交示例（以NexCaptcha为例，伪代码）：

// v3任务创建请求
{
  "clientKey": "your_api_key",
  "task": {
    "type": "GeeTestTaskProxyless",
    "websiteURL": "https://example.com",
    "gt": "从页面提取的gt公钥",
    "challenge": "从页面或后端提取的动态challenge"
  }
}

// v4任务创建请求
{
  "clientKey": "your_api_key",
  "task": {
    "type": "GeeTestV4TaskProxyless",
    "websiteURL": "https://example.com",
    "captchaId": "静态公钥captcha_id"
  }
}

识别任务提交后，通过轮询getTaskResult接口获取结果。v3返回validate与seccode，v4返回lot_number、pass_token等四个字段，注入对应表单字段后提交业务请求。具体轮询、超时处理与错误码映射可以参考验证码API轮询和回调有什么区别和验证码API超时怎么处理。

识别结果与业务提交差异

v3结果注入：

将validate注入表单字段geetest_validate
将seccode注入表单字段geetest_seccode
将原始challenge注入表单字段geetest_challenge
三个字段一起提交到业务后端

v4结果注入：

将lot_number注入表单字段lot_number
将captcha_output注入表单字段captcha_output
将pass_token注入表单字段pass_token
将gen_time注入表单字段gen_time
四个字段一起提交到业务后端，业务后端再按前述HMAC-SHA256机制调用极验校验接口

注意lot_number有效期仅10分钟，识别完成到表单提交之间如果超过10分钟，极验二次校验会返回失败。如果遇到token返回后验证失败的情况，可以参考验证码token返回后验证失败怎么排查逐层定位时效、参数、注入和IP问题。

迁移与兼容性建议

极验v3和v4不能混用，迁移时需要：

前端代码改造：将initGeetest改为initGeetest4，移除challenge请求逻辑，改用静态captcha_id
后端校验改造：将v3的签名比对或接口校验改为v4的HMAC-SHA256签名计算与新接口调用
自动化脚本改造：将v3任务类型改为v4任务类型，移除challenge提取步骤，修改结果字段注入逻辑
测试环境隔离：v3与v4公钥、私钥完全不同，测试时必须使用对应版本的密钥，不能混用

如果业务同时存在v3和v4实例（如部分页面尚未迁移），需要在代码中按页面特征或配置区分版本，调用对应初始化和校验逻辑。

对于已有验证码识别服务的用户，迁移到支持v4的服务时可以小流量对照测试，验证任务类型、参数格式、返回字段和成功率后再全量切换。具体迁移步骤可以参考CapSolver替代方案怎么选或2Captcha替代方案怎么选中的低风险迁移流程。

极验v3与v4的架构差异覆盖初始化、参数、通信、校验和自动化接入全流程。开发与测试人员需要按版本选择对应集成方案，不能直接复用v3代码处理v4任务。如需统一接口处理多种验证码类型（包括极验v3/v4、reCAPTCHA、hCaptcha、Turnstile等），可以查看NexCaptcha首页了解统一REST API与任务计费说明。