调试与排错

规则故障应按 search → detail → play → media 分层定位。越早确认失败阶段，越不容易用错误补丁掩盖真实问题。

快速判断

现象	优先检查
搜索 0 结果	最终请求 URL、关键词编码、响应状态、listPath / CSS 选择器
有搜索但详情为空	seriesId 是否是可跟随 URL、线路/剧集选择器、JSON 路径
play 返回空	episodeId 模板、播放器跳转链、解密参数、Cookie 会话
URL 非空但不能播	Content-Type、Range、媒体 Header、签名过期、误抓图片
仅 App 可用、测试失败	WebView challenge、嗅探、测试超时或站点渲染等待条件
代理开关后才可用	token 与分片出口绑定，检查 directConnection

先验证最终 URL

baseUrl 与规则中的路径会组合。一个常见错误是 baseUrl 已带 /api-prefix，步骤又从 /api 开始，最终请求了错误路由。记录解释器实际请求 URL，不要只看 JSON 片段。

媒体验证

对普通文件可发送小范围请求：

curl -I "https://cdn.example.com/video.mp4"
curl -H "Range: bytes=0-2047" "https://cdn.example.com/video.mp4" -o sample.bin

对 HLS：

1. 获取主清单和媒体清单。
2. 确认响应以 #EXTM3U 开始。
3. 解析至少一个真实分片 URL。
4. 带上与播放器一致的 Header，请求少量分片字节。

URL 非空不是成功标准。海报图、HTML 错误页和过期签名地址都可能是非空字符串。

Header 与 Cookie

• 页面请求头与媒体请求头不是同一概念。
• setMediaHeaders 用于传给播放器的请求。
• Cookie 只应选择协议真正需要的名称或前缀。
• 签名 CDN 有时会拒绝额外 Referer；适配器会对已知签名 URL 做清理，但规则仍应最小化 Header。

代理与直连

默认规则使用系统代理。只有当站点的 token 和媒体请求强制绑定同一出口、且系统代理会造成出口不一致时，才设置：

{
  "directConnection": true
}

不要把它当作“请求失败就试试”的通用开关。它会改变真实用户的网络路径。

WebView 规则

当站点必须执行 JavaScript 或完成 challenge：

{
  "useWebview": true,
  "play": [
    {
      "op": "sniff",
      "goal": "html",
      "readyContains": ["player"],
      "rejectContains": ["challenge"],
      "timeoutMs": 30000,
      "settleMs": 1000
    }
  ]
}

给出明确的就绪和拒绝条件，避免页面尚未完成渲染时过早读取。测试宿主没有 WebView，因此需要在真实客户端验证。

first 回退顺序

把最确定、成本最低的分支放前面：

公开 API → 已知播放器变量 → 通用 videoUrl → WebView sniff

不要把宽泛的 videoUrl 放在专用 API 前面，否则它可能抢先返回错误资源。

站点变慢与规则损坏

真实站点可能只是临时慢、限流或区域不可达。排查时区分：

• JSON / 选择器语法错误。
• 后端超时或 429 / 5xx。
• WebView-only 页面。
• 本机代理或 DNS。
• 真实媒体授权失效。

只有确认协议变化后再修改规则，避免为瞬时网络问题写入长期补丁。