SoNovel书源配置全解析

在使用 SoNovel 时，书源配置往往决定了抓取效率和内容完整性。若想把某个新站点纳入阅读库，必须从结构上拆解它的 API 或网页分页规则，然后在 SoNovel 的 source.json 中精准映射。下面的解析把这套流程拆成了四个可操作的环节，帮助开发者在几分钟内完成一次“上架”。

书源结构概览

SoNovel 采用 JSON 描述书源，每个书源对象包含 name、searchUrl、detailUrl、chapterList、contentUrl 五大必备字段。字段之间通过占位符 {keyword}、{id}、{page} 进行动态拼接，框架在运行时会自动替换。

• name：书源名称，建议使用中文全称，便于 UI 识别。
• searchUrl：搜索接口，必须返回符合 listPattern 正则的章节列表。
• detailUrl：作品详情页，用于抓取简介、封面、作者等元信息。
• chapterList：章节目录的抓取规则，常见为分页 JSON 或 HTML 列表。
• contentUrl：正文获取地址，支持 Ajax 请求或直接的文本块。

关键字段详解

其中 searchUrl 与 detailUrl 往往需要配合正则或 XPath 进行内容抽取。框架提供了 listPattern、detailPattern 两个可选属性，分别对应搜索结果和详情页的匹配模式。举例来说，若搜索返回的是 JSON 数组，listPattern 可以写成 ""id":s*(d+)"，框架会把所有匹配的数字收集为作品 ID。

{
    "name": "轻小说站",
    "searchUrl": "https://api.qns.com/search?kw={keyword}&page={page}",
    "listPattern": ""id":\s*(\d+)",
    "detailUrl": "https://www.qns.com/book/{id}",
    "detailPattern": ""title":"([^"]+)","author":"([^"]+)"",
    "chapterList": "https://api.qns.com/book/{id}/chapters?page={page}",
    "contentUrl": "https://api.qns.com/chapter/{cid}"
}

常见错误与调试

配置后最容易踩的坑往往是正则不匹配或分页参数失效。遇到“空列表”提示时，先打开浏览器的开发者工具，手动请求 searchUrl，检查返回体是否真的包含 listPattern 指定的字段。若返回的是压缩的 JSON，记得在 source.json 中加入 "gzip": true。

• 错误 1：{page} 参数未在 URL 中出现，导致分页永远停留在第一页。
• 错误 2：正则使用了贪婪模式 .*，把整段 HTML 抢走，匹配结果为空。
• 错误 3：请求头缺少 User-Agent，目标站点返回 403。

实战案例：自定义轻小说书源

小明想把最近火爆的「星际轻小说」平台加入 SoNovel。该平台的搜索 API 返回形如 {"data":[{"bid":123,"name":"星际之旅"}]} 的结构，章节列表采用分页 JSON。按照上面的模板，他只需要把 listPattern 改为 "bid":s*(d+)，并在 chapterList 中加入 "pageSize":20 的查询参数。配置完成后，运行 SoNovel --source add star-novel.json，几秒钟内就能在客户端看到 120 部新作品。

配置完成后，马上去尝试吧。