搜索一个书名转了半天圈最后弹出“没有找到相关结果”——这个场景我一年里遇到过几十次。问题九成不在APP本身而在书源。所谓书源导入说的是把一份描述“去哪里搜、怎么解析、正文在哪个位置”的配置文件塞进阅读类APP里让它知道该向哪些站点发起搜索、拿到返回结果后按什么规则抽取书名、作者、目录和正文。做对了一次导入能管很久做错了就会出现“明明导入了 22 个源搜索还是空的”这种尴尬。这篇就围绕“3 分钟配好 22 个书源”这件事展开把书源的文件结构、导入路径、验收标准、失效排查按我实际操作的顺序讲一遍。适合两类人看一类是刚装上阅读APP、连书源是什么都没搞明白的新手另一类是用了一段时间、源越攒越多却越来越不好用的老用户。全程只讨论技术层面的配置与调试导入的书源请确保是你自己有权使用的公开内容或个人自建源。1. 书源不是越多越好先把这 22 个源的底摸清1.1 书源本质上是一份结构化描述文件很多人以为书源是一个“插件”或者“程序”其实不是。它就是一个纯文本的 JSON 对象有些 APP 支持 YAML里面写满了字符串和规则表达式。你可以把它理解成一张“取货单”告诉APP去哪个地址取货搜索接口、货架上怎么挑列表选择器、包装上哪个位置印着名字字段选择器、拆开之后内容在哪一页正文选择器。APP 本身不具备任何抓取能力它只是个执行器书源才是真正的“作业指导书”。一份典型的书源长这样字段名各 APP 略有差异但骨架大同小异{ bookSourceName: 示例源A, bookSourceUrl: https://www.example.com, bookSourceGroup: 自建, bookSourceType: 0, enabled: true, searchUrl: https://www.example.com/search?q{{key}}page{{page}}, ruleSearch: { bookList: css:.result-list li, name: css:.titletext, author: css:.authortext, bookUrl: css:.titlehref }, ruleBookInfo: { name: css:h1text, author: css:.info .authortext, intro: css:.introtext }, ruleToc: { chapterList: css:#list dd a, chapterName: text, chapterUrl: href }, ruleContent: { content: css:#contenthtml, replaceRegex: ##本章未完.*?#### } }看明白这张“取货单”你后面所有的排错就有了抓手。搜索没结果先怀疑searchUrl和ruleSearch详情页一片空白问题一定在ruleBookInfo目录出不来去看ruleToc正文里夹着“本章未完请点击下一页”那就是ruleContent的清洗规则没配。90% 的“书源失效”都能被这四段规则定位掉剩下 10% 才是站点跑路或者加了验证。1.2 为什么是 22 个而不是 2200 个这是我最想先讲清楚的一点。新手最容易犯的错就是把网上能找到的书源全导进去动辄几百上千个然后抱怨“搜索要等半分钟”“老是转圈”。这不是APP的问题是数量本身超出了并发预算。算一笔账就明白了。假设单源平均响应时间 1.2 秒这个数字在跨网络请求里算比较乐观的APP 的搜索并发默认一般设 8 路。22 个源的搜索轮次是 22 ÷ 8 2.75 轮加上最慢那一路的拖尾整体等待大概 3 到 4 秒。用户勉强能接受。但如果你导入 200 个源就是 200 ÷ 8 25 轮即便每轮都按 1.2 秒算也是 30 秒起步而且中间只要有几个超时的“死源”整个搜索就会被拖到一分钟以上。绝大多数人在第 8 秒就已经退出了。所以 22 这个数字不是玄学它是“覆盖面”和“响应速度”之间的一个甜点值。我的经验区间是 15 到 30 个低于 15 个容易出现“这本书只有那一个源有”的覆盖率缺口高于 30 个响应速度断崖式下跌。提示并发数不是越大越好。把并发调到 32 以上很多源站点会直接返回限流页面反而制造出一堆假失效。1.3 挑选书源的三个硬指标拿到一个打包好的 22 源合集别急着全导。我会先按三个维度过一遍筛子不合格的直接删掉宁可最后剩 18 个。第一个指标是搜索命中率。同样搜三本不同类型的书一本大众畅销、一本冷门老书、一本最近更新的连载能命中两本以上的算合格只能命中热门的说明它的搜索接口只是简单的站内模糊匹配覆盖面窄。第二个指标是详情完整度。点进去看书名、作者、简介、封面这几项缺两项以上就不要了。缺字段不只是显示难看很多APP的换源逻辑依赖作者名做匹配作者空着会导致换源时匹配错。第三个指标是正文干净度。这是最容易被忽略的。有些源正文里塞满了“请收藏本站”“本章未完请点击下一页”“手机版阅读网址”甚至中间夹一段推广文字。这类源看着能用实际读起来极为难受而且要花大量时间去写清洗正则性价比极低。指标合格线不合格的典型表现处理方式搜索命中率3 本中命中 ≥2只出热门书、结果全是推荐位降权或删除详情完整度书名/作者/简介/封面缺 ≤1作者全空、简介是一段导航文字降权正文干净度无跨段推广、无“下一页”提示每章结尾都有站点口号写正则清洗洗不干净就删响应速度单次搜索 3s经常超时、返回 5xx直接删除2. 导入前必须做的三件事格式、编码、去重2.1 编码问题看不见的 BOM 头最坑人我见过最多的导入失败不是规则写错是文件编码不对。书源文件在传递过程中经常被各种工具“加工”过最常见的是被记事本另存为带 BOM 的 UTF-8或者干脆被存成了 GBK。这两种情况在APP侧的表现高度一致提示“导入失败”或者“格式错误”但不告诉你错在哪。判断方法很简单用十六进制工具或者命令行看一眼文件头三个字节。如果是EF BB BF那就是 UTF-8 with BOM把它去掉就行。命令行下用sed去 BOMsed -i 1s/^\xEF\xBB\xBF// sources.json如果文件是 GBK 编码中文会变成乱码JSON 解析器会直接报错。转码用 iconv注意源编码和目标编码都要写对iconv -f GBK -t UTF-8 sources.json -o sources_utf8.json注意转码之后一定要用文本编辑器打开看一眼前几个中文字段确认书名、分组名不是“锟斤拷”这类乱码。编码转错方向会二次损坏而且不可逆操作前先备份。2.2 JSON 合法性五个高频语法错误书源文件本质是 JSON只要有一个字符不合规整个文件就废了。我统计过自己踩过的坑五个错误占了绝大多数第一数组和对象搞混。批量书源必须是一个 JSON 数组[ {...}, {...} ]单个书源才是对象{...}。很多人从某处复制了单个源直接粘进批量导入框就会失败。第二末尾多余逗号。enabled: true,}这种写法在 JavaScript 里合法在严格 JSON 里非法。手工改过规则的文件特别容易出这个问题。第三单引号代替双引号。JSON 只认双引号键名和字符串值都一样。第四转义没处理好。正则表达式里经常出现反斜杠比如\d在 JSON 字符串里必须写成\\d否则解析器会把\d当成非法转义。第五注释。JSON 不支持//或/* */注释有人为了标注“这个源是给XX用的”加了一行注释整个文件就废了。校验方式我推荐本地跑一遍比在APP里反复试快得多。有 Node 环境的话一条命令搞定node -e const drequire(./sources.json); console.log(条目数:, Array.isArray(d)?d.length:非数组)没有环境也没关系随便找个在线的 JSON 校验页面粘贴进去看红点位置。这一步花 30 秒能省掉后面半小时的瞎猜。2.3 去重与分组为后面的排错留后路去重这件事很多人觉得没必要反正重复的源搜出来也是同一个结果。但重复源带来的隐性成本很高它会占用并发名额让真正有用的源排队它会让搜索结果出现重复条目你还得手动分辨最要命的是重复源往往指向同一个域名一旦这个域名挂了你会误以为“所有源都失效了”实际上是同一个源被复制了五遍。去重我按两个维度做。按bookSourceUrl去重是主力同一个根域名基本可以认为是同一套规则。按bookSourceName去重作为补充防止有人改了域名但名字没改。手工去重太累用脚本最快import json from urllib.parse import urlparse with open(sources.json, encodingutf-8) as f: data json.load(f) seen, result set(), [] for s in data: host urlparse(s.get(bookSourceUrl, )).netloc if host and host not in seen: seen.add(host) result.append(s) print(f去重前 {len(data)}去重后 {len(result)}) with open(sources_dedup.json, w, encodingutf-8) as f: json.dump(result, f, ensure_asciiFalse, indent2)分组则是给未来铺路。导入时我就按“主力”“备用”“自建”分好主力组只放 10 到 15 个高质量的备用组放那些能用的但优先级低的自建组放自己维护的。这样以后搜索出问题我可以先把备用组整体禁用快速判断是不是源的问题而不用一个个点开关。3. 三分钟导入实操三条路径与逐屏记录3.1 路径一本地文件导入最稳本地文件导入是所有方式里最可控的因为它绕开了网络请求不存在“链接失效”“文件被改”的问题。操作顺序是把整理好的sources_dedup.json传到手机存储微信文件传输助手、数据线、云盘都行打开阅读APP找到书源管理入口点右上角的菜单选“本地导入”在文件选择器里定位到那个文件。这里有个细节很多人踩过文件选择器默认只显示特定后缀的文件。如果你的文件叫sources.json.txt被某些工具自动加了后缀在选择器里是看不见的。要么把后缀改回来要么在选择器里切换“显示所有文件”。我一般直接把文件名改成纯.json避免麻烦。导入完成的标志是弹出一个“成功导入 N 条”的提示。这里要盯住这个 N它必须等于你去重后的条目数。如果少了几条说明有部分 JSON 对象结构损坏被跳过了得回去查。如果提示“导入 22 条跳过 0 条”那就干净利落。导入之后不要立刻去搜索先做一件小事立刻导出一次备份。在书源管理里找“导出”或者“备份”把当前状态存一份。原因很简单接下来你要启用、排序、手动改规则万一改坏了一键恢复比重新导入快得多。我现在养成习惯了任何批量操作之前先备份这个动作花 5 秒能救半小时。3.2 路径二链接导入最方便但坑最多链接导入的体验最好点一下就能拉取适合别人分享给你的场景。但它有三个天然缺陷链接指向的文件可能随时被改或删除拉取过程依赖网络超时会失败部分 APP 对链接内容有大小限制太大的合集会被截断。实操上我一般这样处理。先确认链接能直接返回纯文本 JSON在浏览器里打开那个链接看到的应该是[{...}]这样的内容而不是下载提示页或者 HTML 网页。如果打开是网页那说明这个链接不是直链得找真正的 raw 地址。然后把链接粘贴进APP的“网络导入”框点确认等进度条走完。如果拉取失败优先怀疑三件事链接本身失效、返回内容不是 JSON、返回内容带了 HTML 标签。第三种情况很好判断把链接内容复制出来看一眼开头有没有!DOCTYPE。有的话就是被重定向到了网页这个链接不能直接用。提示链接导入成功后我建议立刻按 3.1 的方法导出一次本地备份。链接随时可能失效但你本地那份不会。3.3 路径三剪贴板与扫码导入应急用剪贴板导入适合单条书源比如你在某处看到一段 JSON复制之后打开APP点“剪贴板导入”就能直接识别。这条路径限制很明确只适合一两条超过五条就不适合了因为你要反复复制粘贴远不如文件导入高效。扫码导入适合从电脑往手机传原理是把 JSON 编码进二维码。但二维码的信息容量有限22 个书源编码进去会变成一个极其密集的大方块手机摄像头识别率很低经常扫不出来。我的实际经验是超过 5 个书源就不要用二维码了老老实实用文件传输稳定得多。导入路径适合数量成功率主要风险我的使用建议本地文件1~500 条高编码、后缀名批量首选网络链接1~200 条中链接失效、返回 HTML临时试用剪贴板1~5 条高复制不完整单条调试二维码1~5 条低容量超限、识别失败基本不用3.4 导入后的第一屏三条命令式检查导入完成别急着搜书。我固定会做三个动作加起来不到 30 秒但能挡掉后面大部分麻烦。第一确认启用状态。有些合集里enabled字段是false导进去 22 条实际全是关闭的搜索当然没结果。进书源列表看一眼有没有灰色的全选启用。第二确认分组标签。看bookSourceGroup有没有正确识别如果全堆在“未分组”里说明这个字段在解析时丢了后面管理会很痛苦。这种情况我一般手动批量改一次分组比重新导入省事。第三确认类型过滤。书源有个“类型”字段0 通常是文本1 是音频2 是图片。如果合集里混进了音频源它们会出现在搜索列表里但点开没正文看起来像“坏了”。搜索设置里把类型限定为文本能过滤掉这批干扰项。4. 导入成功不等于能用五项验收与排序策略4.1 五项验收一项都不能省“导入 22 条成功”只是文件层面的成功不代表这些源真的可用。我有一套固定的五项验收每次导入新合集都跑一遍大概两分钟。**第一项搜索验收。**搜一本大众书、一本冷门书、一本新书。大众书看命中数量冷门书看覆盖率新书看时效性。三项都过说明这批源的搜索链路是通的。**第二项详情验收。**随便点开一个搜索结果看书名、作者、简介、封面。作者字段为空是最常见的缺陷因为很多站点的列表页不返回作者需要详情页二次解析规则写得不全就丢了。**第三项目录验收。**点“目录”或者“开始阅读”看章节列表能不能出来。目录出不来通常不是网络问题是ruleToc里的选择器匹配不上比如站点把dd改成了li。**第四项正文验收。**打开第一章往下读三屏。重点看两件事内容是不是完整的有没有半截截断、有没有夹带推广文字。**第五项换源验收。**这是最容易被跳过但最关键的一项。人工制造一次换源进入阅读界面调出菜单选“换源”看能不能列出同一本书的其他源。如果换源列表是空的说明这批源的作者/书名匹配规则有问题等于断了一条腿。验收项检查方法不合格的典型症状根因定位搜索搜 3 本不同类型的书完全无结果searchUrl / ruleSearch详情点开看四项信息作者空、简介是导航文字ruleBookInfo目录点目录看章节数章节数为 0 或只有 1 章ruleToc正文读 3 屏内容截断、夹推广ruleContent换源手动换源看列表列表为空书名/作者匹配规则4.2 排序与权重让好源先说话22 个源不可能质量一样。搜索时APP会按顺序并发请求返回快的、质量高的排在前面体验就好得多。排序这件事有两个层次。手动排序是最直接的。在书源列表里长按拖拽把验收表现最好的三五个源拖到最前面。这招笨但有效我一般在验收完之后立刻做一次把明显好用的拖到顶部。权重字段是进阶做法。部分 APP 支持weight或者customOrder字段数值越小越靠前。批量调整的时候可以写个脚本按验收结果打分排序# 按响应速度和验收得分重排score 越小越优先 sources.sort(keylambda s: (s.get(weight, 100), -s.get(score, 0)))排完序还有个隐性收益搜索结果去重时排在前面的源会“赢”用的就是它的书名和简介。好源在前面搜索列表看起来就整齐不会出现一堆带站点水印的书名。4.3 分组启停把 22 个源拆成三档用我一直建议把源分成三档管理这不是形式主义是排错效率的关键。常驻档放 10 到 15 个验收全过、响应快、正文干净保持常开。备用档放 5 到 8 个能搜到但正文有瑕疵或者偶尔超时平时禁用只在新书搜不到的时候手动开一下。观察档放剩下的规则可疑但还没确认留着但不启用。这样分的好处是当出现“搜不到书”的投诉时你可以做一次快速排除先把常驻档里的一半禁用再搜如果结果出现说明问题在被禁用的那批里如果还是没结果说明问题在还在启用的那批或者APP设置上。二分法定位比一个个开关快得多。注意备用档和观察档不要图省事全启用。它们占的不只是列表空间是每次搜索的并发名额和时间预算。5. 书源失效排查从现象到根因的定位流程5.1 失效的六种真实原因“书源失效”是一个笼统的说法实际上至少有六种完全不同的原因处理方式也完全不一样。分不清原因就到处改规则只会越改越乱。第一种站点改版。这是最主流的占我遇到的失效的一半以上。站点把列表结构从ul li改成div选择器就全错了。特征是以前能用某天突然全部搜不到但站点本身访问正常。第二种接口地址变了。搜索接口从/search?q改成/s?keywordsearchUrl里的拼接就失效了。特征是搜索返回 200 但结果是空的或者返回的是首页 HTML。第三种加了请求校验。站点要求特定的User-Agent或者Referer不带就返回空页。特征是在浏览器里能打开在APP里就是空。第四种源站点彻底关闭。域名解析不了或者返回 404/502。这种最简单直接删。第五种限流与频控。请求太频繁被临时阻断表现为“刚才还能用突然全挂”。等一段时间或者降并发就能恢复。第六种规则本身写错了。从别人那里抄来的规则字段名对不上你用的APP版本。这种从导入第一天就是坏的不是“失效”。5.2 单源调试把黑盒拆开看定位到具体某个源之后接下来要做的是单源调试。核心思路是把“搜索”这个黑盒拆成三段逐段验证。第一段验证接口。把searchUrl里的占位符替换成真实关键词拼成一个完整地址比如把{{key}}换成测试注意做 URL 编码。然后把这个地址在浏览器里打开看返回的是不是包含书籍列表的 HTML 或者 JSON。如果这一步就没数据后面全白搭直接判定为接口问题。第二段验证选择器。拿到返回内容之后用浏览器的开发者工具打开同一个页面按 F12用元素选择器点一下书名看它对应的 CSS 选择器是什么。然后和你书源里的ruleSearch.name对比。这一步能解决八成“规则写错”的问题。第三段验证字段映射。有时候选择器对了但取到的内容是错的比如取到了a标签里的推广文字而不是书名。这时候要在选择器后面加属性限定text取文本、href取链接、html取内部 HTML。这几个后缀写错表现就是“有结果但字段是空的”。5.3 规则写法速查四种语法别搞混书源规则支持好几种语法混用是新手最常见的错误来源。我把常用的四种整理成表遇到看不懂的规则先对一下这张表。语法前缀类型典型写法适用场景css:CSS 选择器css:.list li .nametextHTML 结构规整的站点XPath:XPath 路径XPath://div[idlist]/a结构复杂、层级深的页面json:JSONPathjson:$.data.list[*].name返回 JSON 的接口##正则##正则替换##本章未完.*?##清洗正文里的多余文字正则替换这块特别值得单独说一句。它的语法是##匹配内容##替换内容##中间用##分隔。如果只想删掉不想要替换替换部分留空就行。举个实际例子正文里每章结尾都有“本章未完请点击下一页继续阅读”清洗规则写成##本章未完[^\n]*##这里用[^\n]*而不是.*是因为.*在某些实现里会跨行匹配把整章内容都吃掉。这是个很隐蔽的坑我第一次写的时候就把整章正文清空了还以为源坏了。5.4 批量排查先分组禁用再二分定位22 个源同时出问题逐个调试太慢。我的做法是先做一次“全局排除”确认问题在源还是在APP。先禁用全部书源只启用一个确定好用的搜一下。如果这一个能出来结果说明APP本身没问题问题在其余源。如果这一个也出不来那问题在APP层面——搜索设置、网络权限、类型过滤都有可能。确认问题在源之后用二分法启用一半搜有结果就说明问题在禁用的那一半没结果就在启用的这一半。22 个源最多 5 轮就能锁定到具体某几个每轮搜索加判断不到 20 秒总共两分钟内解决。6. 常见问题速查与踩坑实录6.1 问题速查表下面这张表是我这几年被问得最多、自己也踩过的问题汇总遇到状况先在这里对一遍比漫无目的地试要快得多。现象最可能的原因排查顺序解决方式导入提示格式错误JSON 不合法 / BOM 头先校验 JSON再看文件头去 BOM、修语法导入成功但搜索无结果源默认关闭 / 类型过滤看书源列表是否灰色批量启用、限定文本类型只有部分源有结果其余源接口已变逐个验证 searchUrl修规则或删除搜索结果重复多条同域名源重复导入按 bookSourceUrl 去重脚本去重详情页作者为空ruleBookInfo 缺字段看详情页 HTML 结构补选择器目录只有一章ruleToc 匹配到了错误节点检查选择器层级换选择器正文夹推广文字未配 replaceRegex看正文源码加正则清洗正文被整章清空正则用了.*跨行检查正则改[^\n]*换源列表为空书名/作者匹配失败检查作者字段补作者规则用一段时间突然全挂限流 / 站点改版单源验证接口降并发或换源搜索特别慢源数量超并发预算数一下启用数量砍到 30 以内导入后规则被改回自动更新覆盖了手改看更新设置关闭自动更新6.2 踩坑实录三件文档里不会写的事第一件关于“一键更新书源”。很多APP有书源自动更新功能看着很贴心实际是个陷阱。你手动调好的规则一次自动更新可能就被覆盖回原样而且不提示。我现在一律关掉自动更新需要更新的时候手动点更新前先导出备份。这个习惯救过我好几次。第二件关于“导入 22 条跳过 5 条”。早期我看到跳过的数字不在意觉得 17 条也够用。后来发现被跳过的往往是结构最新的那几条因为它们用了新字段而旧版APP解析不了。所以“跳过 N 条”这个数字其实是在提示你APP 版本可能该更新了或者这批源是给更高版本准备的。现在我只要看到跳过数不为零就会去看一眼被跳过的是什么。第三件关于“正文看起来正常但有隐藏水印”。有些源的正文里夹着零宽字符或者同色文字肉眼看不出来复制出来才会发现。这类内容很难用正则直接清因为字符本身不可见。判断方法是全选正文复制到记事本看有没有多余的空白段落。有的话用[\u200b-\u200f\u202a-\u202e]这类不可见字符范围做一次批量替换。这个问题比较冷门但遇到了会很困扰。6.3 我个人的维护节奏书源这东西不是导入一次就一劳永逸的。我给自己定了个很轻的维护节奏每个月花十分钟搜三本书测一下发现失效的就删掉或者标记为观察档每季度做一次全量验收把明显退化的源清理掉从备用档补几个上来。这样维护成本很低但源池一直保持着比较健康的状态。另外我强烈建议养成一个习惯任何批量操作之前先导出备份。启用、禁用、排序、改规则这四个动作都有把配置搞乱的风险备份一次五秒钟恢复一次也是五秒钟而不备份的代价往往是半小时起步的重建。这个投入产出比怎么算都划算。再补一个我自己用了很久的小技巧在书源名字前面加序号前缀比如01-主力A、11-备用B这样列表天然就是按我的优先级排的不用依赖APP的拖拽排序换个设备导入之后顺序也不会乱。名字改起来麻烦一次后面省心很久。最后说个实在话书源的本质是“别人维护的规则”它天然会失效这是这个模式的固有成本。真正稳的做法是慢慢积累几个自己维护的源规则自己写、自己调站点变了第一时间能修。22 个现成的源是个很好的起点但别把它当成终点。