人机验证应对

本文面向规则作者，讲解当目标站在搜索 / 访问阶段被人机验证拦截时，如何用规则根级的 antiCrawlerConfig 应对。反爬配置挂在规则根级，仅在 XPath 搜索阶段被验证页替代时生效。【skill 资料】官方文档原文称：「反反爬虫：用于 XPath 搜索响应被验证页替代的情况。应根据网站实际验证方式配置检测条件和交互步骤。」

一、先判断：被拦后到底是哪一类页面

动手配 antiCrawlerConfig 之前，必须先用浏览器（或 curl）实际访问目标站的搜索地址，看清被拦后返回的到底是什么页面，再决定走哪一档，严禁套模板：

1. 普通图片验证码页：返回的不是结果列表，而是一张图形验证码 <img> + 一个输入框 + 一个提交按钮，需要人工（或打码服务）辨认字符后提交。→ 见下文第 1 档。
2. 点击 / 滑块 / 行为验证页：一个「点击按钮继续 / 我不是机器人」的过渡页，或滑块拼图、点选文字等行为验证。→ 见下文第 2 档（注意：真滑块拼图 / 点选 / 行为验证并不能自动解）。
3. Cloudflare CF / Akamai 等智能风控页：出现 “Just a moment…”、challenge、Ray ID、Akamai Bot Manager 等字样，需要 JS 执行甚至真实浏览器环境才能放行。→ 见下文第 3 档，常需配合根级 useWebview。
4. 只是登录拦截：没有任何验证交互，只是 302 跳到登录页 / 弹窗登录。这不属于人机验证，应走 需要登录后才能观看（配 needLogin / loginURL），而不是开 antiCrawlerConfig。

二、三档对照总表（核心）

【fork 源码 / skill 资料】按 MCP 档位映射口径，三档与 captchaType 的对应关系如下。无论哪一档，antiCrawlerConfig 对象都必须完整给出（带 enabled 等全部字段），不能只写一个数字。

三、字段总表

【skill 资料】字段名以规则校验器 kazumi_rule_codec.ts 的实际实现为准（注意：验证方式字段叫 captchaType，不叫 mode）：

校验器硬性约束：captchaType 与 captchaDetectType 只能取 1、2、3，否则报 must be 1, 2, or 3。

四、检测方式：captchaDetectType 怎么选

应用靠 captchaDetectType + captchaDetectValue 判断「这次搜索响应是不是被验证页替换了」。三种检测方式：

• captchaDetectType: 1 —— XPath 节点存在：captchaDetectValue 写一个 XPath（如 //form[@id='captcha-form'] 或 //div[@id='check-wrap']）。页面中存在该节点即判定为被拦截。
• captchaDetectType: 2 —— 文本匹配：captchaDetectValue 写一段特征文字（如 请输入验证码）。响应页面包含这段文字即判定为被拦截。
• captchaDetectType: 3 —— 正则匹配：captchaDetectValue 写一个正则（如 challenge\.js|安全验证）。页面 HTML 命中该正则即判定为被拦截。

五、三档完整可抄 JSON 示例

第 1 档：captchaType = 1（普通图片验证码）

适用场景：搜索请求返回带图形验证码的页面，需要展示图片、人工（或接打码服务）输入后提交。

{
  "api": "1",
  "type": "anime",
  "name": "示例图片验证码站点",
  "version": "1.0",
  "baseURL": "https://captcha-demo.example.com/",
  "searchURL": "https://captcha-demo.example.com/search?wd=@keyword",
  "searchList": "//div[@class='search-item']",
  "searchName": "//h3/a",
  "searchResult": "//h3/a",
  "chapterRoads": "//div[@class='playlist-box']",
  "chapterResult": "//ul/li/a",
  "searchMode": "xpath",
  "chapterMode": "xpath",
  "antiCrawlerConfig": {
    "enabled": true,
    "captchaType": 1,
    "captchaDetectType": 2,
    "captchaDetectValue": "请输入验证码",
    "captchaImage": "//img[@id='captcha_img']",
    "captchaInput": "//input[@name='captcha']",
    "captchaButton": "//button[@id='submit_btn']",
    "captchaScript": ""
  }
}

• captchaDetectType: 2 + captchaDetectValue: "请输入验证码" 表示：搜索响应页面包含「请输入验证码」这段文字时，判定为被拦截。
• 命中拦截后，应用用 captchaImage 取出验证码图片展示出来，等用户输入后填入 captchaInput，再点击 captchaButton 提交。
• 检测也可换成 captchaDetectType: 1（此时 captchaDetectValue 写 XPath）或 captchaDetectType: 3（写正则）。

第 2 档：captchaType = 2（自动点击）

适用场景：拦截页只是一个「点击按钮继续 / 我不是机器人」的过渡页，不需要输入字符，自动点一下按钮就能放行。

{
  "api": "1",
  "type": "anime",
  "name": "示例点击验证站点",
  "version": "1.0",
  "baseURL": "https://click-demo.example.com/",
  "searchURL": "https://click-demo.example.com/search?wd=@keyword",
  "searchList": "//div[@class='search-item']",
  "searchName": "//h3/a",
  "searchResult": "//h3/a",
  "chapterRoads": "//div[@class='playlist-box']",
  "chapterResult": "//ul/li/a",
  "searchMode": "xpath",
  "chapterMode": "xpath",
  "antiCrawlerConfig": {
    "enabled": true,
    "captchaType": 2,
    "captchaDetectType": 1,
    "captchaDetectValue": "//div[@id='check-wrap']",
    "captchaImage": "",
    "captchaInput": "",
    "captchaButton": "//button[@id='pass-check']",
    "captchaScript": ""
  }
}

• captchaType: 2 时不需要 captchaImage / captchaInput，只需要把 captchaButton 指向那个「放行」按钮。
• 检测条件这里用 captchaDetectType: 1（XPath 节点存在）：页面出现 #check-wrap 过场容器时，自动点击 #pass-check。

第 3 档：captchaType = 3（自定义 JS）

适用场景：拦截页需要执行一段页面内脚本（比如调用页面自带的 JS 函数、操作 cookie、跳转特定 URL）才能放行；Cloudflare CF、Akamai 等智能风控站一般走这一档。

{
  "api": "1",
  "type": "anime",
  "name": "示例JS验证站点",
  "version": "1.0",
  "baseURL": "https://jscheck-demo.example.com/",
  "searchURL": "https://jscheck-demo.example.com/search?wd=@keyword",
  "searchList": "//div[@class='search-item']",
  "searchName": "//h3/a",
  "searchResult": "//h3/a",
  "chapterRoads": "//div[@class='playlist-box']",
  "chapterResult": "//ul/li/a",
  "searchMode": "xpath",
  "chapterMode": "xpath",
  "antiCrawlerConfig": {
    "enabled": true,
    "captchaType": 3,
    "captchaDetectType": 3,
    "captchaDetectValue": "challenge\\.js|安全验证",
    "captchaImage": "",
    "captchaInput": "",
    "captchaButton": "",
    "captchaScript": "document.cookie='pass=ok;path=/';location.reload();"
  }
}

• captchaType: 3 时，命中拦截后应用在该页面 WebView 上下文里执行 captchaScript 这段 JS。
• 这里 captchaDetectType: 3 是正则匹配，页面 HTML 里出现 challenge.js 或「安全验证」字样即触发。
• 【经验】脚本怎么写取决于站点拦截页的实际逻辑：常见套路是种一个放行 cookie 后 location.reload()，或调用页面已有的验证函数。拿不准的 API 就先在浏览器 Console 里手工跑通再抄进来。

六、useWebview：什么时候要开

【fork 源码】useWebview 是规则根级的布尔字段（不在 antiCrawlerConfig 内部），规则模板里常见写法是 "useWebview": true。它的作用是让该规则的页面请求走真实 WebView 浏览器内核，而不是纯 HTTP 拉 HTML——对依赖 JS 渲染、或带智能风控的站点有效。

• 普通 XPath 站（服务端直接吐 HTML）不需要开 useWebview，纯请求 + XPath 更快更省。
• 第 3 档的 CF / Akamai 等智能风控站，常需要 captchaType: 3 配 useWebview: true：用真实浏览器内核加载拦截页，再在其上下文执行 captchaScript，才有机会种下放行 cookie / 跑完 challenge 跳转。

根级示意（与 antiCrawlerConfig 并列，不嵌套）：

{
  "api": "1",
  "type": "anime",
  "name": "示例真实浏览器内核站点",
  "version": "1.0",
  "baseURL": "https://webview-demo.example.com/",
  "useWebview": true,
  "searchMode": "xpath",
  "chapterMode": "xpath",
  "antiCrawlerConfig": {
    "enabled": true,
    "captchaType": 3,
    "captchaDetectType": 3,
    "captchaDetectValue": "challenge\\.js|安全验证",
    "captchaImage": "",
    "captchaInput": "",
    "captchaButton": "",
    "captchaScript": "document.cookie='pass=ok;path=/';location.reload();"
  }
}

七、关闭反爬配置：骨架保留不要删

不需要反爬时保留默认骨架即可（enabled: false，其余字段空串），不要整段删掉——完整规则骨架里始终带这个对象：

"antiCrawlerConfig": {
  "enabled": false,
  "captchaType": 1,
  "captchaImage": "",
  "captchaInput": "",
  "captchaButton": "",
  "captchaDetectType": 1,
  "captchaDetectValue": "",
  "captchaScript": ""
}

八、常见坑（与验证码相关）

1. captchaType 不是 mode：字段名是 captchaType，检测类型是 captchaDetectType，两个都只能取 1/2/3。写成 "mode": 1 校验器不认。
2. 验证码图片用 XPath 定位，不要手写图片 URL：captchaImage 填的是指向验证码 <img> 节点的 XPath，由应用在 WebView 里取出展示，不需要你在 JSON 里手写图片 URL。
3. curl 调试验证码要带会话 Cookie：验证码图片通常和验证页面共享同一个会话 Cookie。直接 curl -O 图片地址而不带刚才拿到的 Cookie，拿到的是另一张图，永远对不上。
4. 反爬配置只对 XPath 搜索阶段生效：antiCrawlerConfig 管的是「搜索那一下」被验证页替换的情况；选集阶段、播放页阶段被拦，它管不到。API 模式的请求被 403 / 拦截，要去补 API 请求 request.headers 里的 Referer / UA / Cookie，而不是去开 antiCrawlerConfig。
5. 强人机验证不要硬刚，优先换源：滑块拼图、点选文字、Cloudflare Turnstile 等强验证，自动点击 / 一段 JS 基本解不开，优先选择结构更稳定、无需复杂验证的来源，或改用其公开 JSON 接口写 API 规则；实在无法自动处理时，在规则说明中标注需要用户手动配合。

相关文档

• 需要登录后才能观看 —— 被拦只是要求登录（而非人机验证）时，配 needLogin / loginURL。
• XPath 规则开发 —— antiCrawlerConfig 生效的 XPath 搜索阶段与字段基础。

樱花动漫 · 基于 Flutter · 开源 GPL-3.0 · 规则格式兼容 Kazumi