Kazumi XPath规则编写完整教程：从入门到精通
一、基础概念解析
什么是 Kazumi 规则？
Kazumi 规则是一套基于 JSON 格式的配置文件，用于定义如何从特定网站采集番剧资源。它采用 XPath 选择器语法，让用户无需编写复杂代码，就能快速构建自定义的视频源适配方案。每条规则最多使用五行 XPath 选择器，即可完成从搜索、列表解析到播放链接提取的完整流程。
核心价值与应用场景
核心价值：资源聚合（整合多平台番剧）、个性化定制（添加特定视频源）、社区共享（规则可导出分享）。
典型场景：添加新番剧网站作为视频源、适配网站改版后的页面结构、创建特定内容的专用采集规则。
二、环境准备
开发工具
表格
| 工具 | 用途 |
|---|---|
| 文本编辑器 | 编写 JSON 规则文件（推荐 VS Code） |
| 浏览器开发者工具 | 分析网页结构、测试 XPath |
| Kazumi 客户端 | 测试规则效果 |
前置知识
-
JSON 基础：理解对象、数组、键值对结构
-
XPath 语法：路径表达式、谓词、属性选择
-
HTML 结构：DOM 树、标签、class/id 定位
⚠️ 重要限制：Kazumi 当前仅支持以 // 开头的 XPath 选择器。
XPath 核心语法速查：
表格
| 表达式 | 说明 | 示例 |
|---|---|---|
| // | 任意层级查找 | //div 查找所有 div |
| @ | 选择属性 | //img/@src |
| 条件筛选 | //div[@class=‘list’] | |
| text() | 文本内容 | //h3/text() |
三、核心语法详解
规则文件结构
{ "api": "3", "type": "anime", "name": "规则名称", "version": "1.0", "muliSources": true, "useWebview": true, "useNativePlayer": true, "userAgent": "", "baseURL": "https://example.com/",
可以参考用 Nginx Proxy Manager 统一管理。 "searchURL": "https://example.com/search?wd=@keyword", "searchList": "//div[@class='result-list']/div", "searchName": ".//h3/a/text()", "searchResult": ".//h3/a/@href", "chapterRoads": "//ul[@class='episode-list']", "chapterResult": ".//li/a"}关键字段说明
基础字段： api（API 版本）、 type（固定为 anime）、 name（规则名称）、 version（版本号）
行为控制字段：
-
useWebview：使用 WebView 渲染页面
-
useNativePlayer：使用内置播放器（无法播放时可设为 false）
-
adBlocker：HLS 广告过滤（API Level 5+）
数据提取字段：
-
baseURL：网站基础地址
-
searchURL：搜索 URL， @keyword 为关键词占位符
-
searchList：搜索结果容器选择器
-
searchName：番剧名称（相对路径）
-
searchResult：详情页链接（相对路径）
-
chapterRoads：章节列表容器
-
chapterResult：播放链接（相对路径）
API Level 选择指南
表格
| API Level | 功能特性 |
|---|---|
| 1 | 基础搜索与播放 |
| 2 | 支持 POST 请求 |
| 3 | 支持 Referer、传统解析器（推荐） |
| 5 | HLS 广告过滤 |
四、规则编写流程
以实际案例演示完整开发流程。
步骤一：分析网页结构
访问目标网站，使用浏览器开发者工具（F12）分析：
-
搜索 URL 模式
-
搜索结果列表的 HTML 结构
-
详情页章节列表结构
步骤二：编写选择器
在 Console 中使用 $x(“//your-xpath”) 测试：
// 测试搜索结果列表$x("//div[@class='search-results']/div")
// 测试名称提取$x("//div[@class='search-results']/div[1]//h3/text()")步骤三：组装规则文件
{ "api": "3", "type": "anime", "name": "示例动漫站", "version": "1.0", "useWebview": true, "useNativePlayer": true, "baseURL": "https://example-anime.com/", "searchURL": "https://example-anime.com/search?q=@keyword", "searchList": "//div[@class='search-results']/div[@class='item']", "searchName": ".//h3/text()", "searchResult": ".//a/@href", "chapterRoads": "//ul[@class='episode-list']", "chapterResult": ".//li/a"}步骤四：测试验证
在 Kazumi 中导入规则，依次测试搜索、详情页、播放功能。
五、高级技巧与最佳实践
反爬虫配置
针对有验证码的网站：
{ "antiCrawlerConfig": { "enabled": true, "captchaType": 1, "captchaImage": "//img[@class='verify-img']", "captchaInput": "//input[@class='verify-input']", "captchaButton": "//button[@class='verify-btn']" }}常见问题排查
表格
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 搜索无结果 | 选择器错误 | 浏览器测试 $x() |
| 无法播放 | 播放器不兼容 | useNativePlayer: false |
| 规则失效 | 网站改版 | 更新选择器 |
最佳实践
-
选择器健壮性：优先使用 contains() 匹配 class
-
版本管理：每次修改更新 version 字段
-
多源支持： muliSources: true 配合分组选择器
六、实战案例分析
案例一：基础规则（API Level 1）
{ "api": "1", "type": "anime", "name": "AGE动漫", "version": "1.5", "muliSources": true, "useWebview": true, "useNativePlayer": true, "baseURL": "https://www.agedm.io/", "searchURL": "https://www.agedm.io/search?query=@keyword", "searchList": "//div[2]/div/section/div/div/div/div", "searchName": "//div/div[2]/h5/a", "searchResult": "//div/div[2]/h5/a", "chapterRoads": "//div[2]/div/section/div/div[2]/div[2]/div[2]/div", "chapterResult": "//ul/li/a"}特点：结构简洁，适合标准化网站，多源支持处理不同播放线路。
案例二：广告过滤规则（API Level 5）
{ "api": "5", "type": "anime", "name": "DM84", "version": "1.4", "muliSources": true, "useWebview": true, "useNativePlayer": true, "adBlocker": true, "baseURL": "https://dmbus.cc/", "searchURL": "https://dmbus.cc/s----------.html?wd=@keyword", "searchList": "//div/div[3]/ul/li", "searchName": "//div/a[2]", "searchResult": "//div/a[2]", "chapterRoads": "//div/div[4]/div/ul", "chapterResult": "//li/a"}特点：启用 adBlocker 过滤 HLS 广告，选择器路径简洁高效。
案例三：反爬虫规则（API Level 6）
{ "api": "6", "type": "anime", "name": "xfdm", "version": "2.0", "muliSources": true, "useWebview": true, "useNativePlayer": true, "useLegacyParser": true, "baseURL": "https://dm.xifanacg.com/", "searchURL": "https://dm.xifanacg.com/search.html?wd=@keyword", "searchList": "//div[@class='vod-detail style-detail cor4 search-list']", "searchName": "//div/div[2]/a/h3", "searchResult": "//div/div[2]/a", "chapterRoads": "//ul[@class='anthology-list-play size']", "chapterResult": "//li/a", "antiCrawlerConfig": { "enabled": true, "captchaType": 1, "captchaImage": "//img[@class='ds-verify-img']", "captchaInput": "//div[4]/div[2]/div/div/input", "captchaButton": "//div[4]/div[2]/button" }}特点：完整反爬虫配置，自动处理图片验证码，传统解析器提升兼容性。
七、扩展资源
官方资源
表格
| 资源 | 链接 |
|---|---|
| Kazumi 官网 | https://kazumi.app |
| 官方文档 | https://kazumi.app/docs |
| 规则仓库 | Predidit/KazumiRules GitHub |
| 主项目 | Predidit/Kazumi GitHub |
学习路径建议
入门：阅读现有规则 → 浏览器练习 XPath → 修改规则实验
进阶：独立编写新规则 → 学习反爬虫配置 → 提交社区贡献
贡献指南
向 KazumiRules 提交规则：Fork 仓库 → 创建 JSON 文件 → 本地测试 → 提交 Pull Request注意：不要手动修改 index.json，该文件会在 PR 合并后自动更新。
支持与分享
如果这篇文章对你有帮助，欢迎分享给更多人或赞助支持！
