ReadCat 书源插件极简上手写 3 个方法跑通从搜索到正文的完整阅读链路【免费下载链接】read-cat一款免费、开源、简洁、纯净、无广告的小说阅读器项目地址: https://gitcode.com/gh_mirrors/re/read-cat晚上十一点你在阅读器里搜一本冷门小说弹出的却是结果为空和半屏广告。这种体验ReadCat 想彻底终结——它是一款免费、开源、简洁、纯净、无广告的小说阅读器而它的在线内容全部来自书源插件也就是由你这样的开发者用代码定义去哪找书、怎么解析。这篇教程会带你从零写出第一个真正能用的书源跑通搜索、详情、正文三个环节全程约 20 分钟。先解决一个实际问题为什么 ReadCat 坚持用插件把书源做成插件就像浏览器把能力交给扩展核心只管阅读体验去哪找书完全外包。好处很明显——网站改版了你更新插件就行不必等客户端发版不想用的站点随时禁用。ReadCat 默认不携带任何书源首次使用时空空如也但这恰恰是它干净的原因内容来源由你掌控。先别急着理解全部原理。照着下面做让一个假书源先跑起来你会立刻明白三个方法在阅读器里各自扮演什么角色。跑通第一个最小示例让 ReadCat 认识你的书源新建一个my-first-source.js粘贴下面这段代码class MyFirstSource { static ID myfirstsource20260813001; static TYPE 0; static GROUP 我的测试; static NAME 我的第一个书源; static VERSION 1.0.0; static VERSION_CODE 1; static PLUGIN_FILE_URL ; static BASE_URL https://example.com; constructor({ request, cheerio, store }) { this.request request; this.cheerio cheerio; this.store store; } async search(searchkey) { return [{ bookname: 测试小说, author: 佚名, detailPageUrl: https://example.com/book/1 }]; } async getDetail(detailPageUrl) { return { bookname: 测试小说, author: 佚名, coverImageUrl: , intro: 一本用于学习的测试书, chapterList: [{ title: 第一章, url: https://example.com/book/1/c1, index: 0 }] }; } async getTextContent(chapter) { return [这是正文的第一段。, 这是正文的第二段。]; } } plugin.exports MyFirstSource;这段代码做了什么先说静态属性——它们是插件的身份证ReadCat 导入时会逐一校验ID必须是 16 到 32 位的字母数字组合TYPE用 0 表示书源1 是书城2 是朗读引擎NAME和GROUP各限制在 15 个字符内BASE_URL必须以 http 或 https 开头。这些规则全部写在src/core/plugins/index.ts的校验逻辑里。构造函数里ReadCat 会注入三件套request网络请求、cheerioHTML 解析用法和 jQuery 一致、store键值缓存。随后实现三个核心方法search返回搜索结果列表getDetail返回详情和章节数组getTextContent返回正文段落数组。最后用plugin.exports导出类这是沙箱约定的出口。保存后打开 ReadCat 的「设置 → 插件」点导入按钮选中这个文件启用它再去搜索页随便搜个关键词——测试小说真的出现了。一个能搜、能进详情、能翻正文的完整书源就这样跑通了。三个方法对应阅读器的三次动作现在原理已呼之欲出一次阅读行为本质就是三次方法调用。search(searchkey)对应搜书动作返回SearchEntity列表核心字段是bookname、author、detailPageUrl。getDetail(detailPageUrl)对应打开详情页动作必须返回chapterList章节数组每章带title、url、index。getTextContent(chapter)对应翻开正文的动作返回一个字符串数组每个元素是一段。另外要注意ReadCat 会在你返回正文后自动做一次 HTML 消毒sanitizeHTML把脚本和垃圾标签过滤掉——这一点在踩坑环节还会遇到。接入真实网站请求、解析与乱码假书源跑通后把硬编码数据换成真实请求即可。请求统一走注入的this.request.get跨域问题已经替你处理好了async search(searchkey) { const { body } await this.request.get( ${MyFirstSource.BASE_URL}/search?q${encodeURIComponent(searchkey)}, { charset: UTF8, headers: { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) } } ); const $ this.cheerio.load(body); return $(.book-item).map((i, el) ({ bookname: $(el).find(.name).text().trim(), author: $(el).find(.author).text().trim(), detailPageUrl: $(el).find(a).attr(href), })).get(); }charset用于指定网页编码——国内不少站点仍是 GBK读错了就是满屏乱码headers里带上正常的User-Agent能降低被反爬拦截的概率。getDetail和getTextContent套路相同请求 URL →cheerio.load解析 → 提取字段返回。请求配置支持的全部参数见src/core/request/defined/request.d.ts。踩坑实录新手最容易翻车的四个场景导入时报Property not found。大概率是静态属性拼错或ID位数不在 16 到 32 之间对照校验规则逐项检查即可。正文全是乱码。把charset从UTF8改成GBK同理提交参数的编码urlencode也要和站点保持一致。能搜到书正文却为空。常见原因是正文由 JavaScript 动态渲染静态 HTML 里根本没有或是返回内容被消毒逻辑过滤成了空串。前者去换一个能拿到数据的接口后者检查正文是否藏在script或iframe标签里。请求被网站拒绝。先补全headers仍不行可在请求配置里加proxy: true再到设置里开启代理——ReadCat 的请求层对代理支持得很完整。进阶一步开发调试、缓存与自动更新别再用改代码 → 重新导入的笨办法了。ReadCat 在设置里内置了插件开发工具导入官方工具包、配置端口后点「启动」即可在浏览器里热调试插件相关代码在src/core/plugin-devtools/与electron/plugin-devtools.ts。调试稳定后有三件事值得做一是用store.setStoreValue / getStoreValue缓存搜索结果减少重复请求二是给PLUGIN_FILE_URL填上插件文件的在线地址用户就能通过「更新」按钮一键升级网站改版时不必挨个通知三是用 try/catch 兜住请求失败的场景给出友好提示而不是让阅读器抛一屏红色堆栈。下一步把插件变成你的作品从最小示例到真实书源你已经走完了插件开发 90% 的路。剩下 10% 是细节目录去重、分页加载、封面图处理、不同站点的差异兼容。想参考完整实现内置的 Edge TTS 朗读引擎src/core/plugins/built-in/tts/edge.ts就是一份活教材接口定义在src/core/plugins/defined/booksource.d.ts插件的存储与状态管理在src/store/plugins.ts。想深入参与可以git clone https://gitcode.com/gh_mirrors/re/read-cat拉取源码边看边改。写出的第一个书源哪怕只是为某个冷门站点做了适配也值得分享给社区——开源项目的生命力正是由一个个没人愿意做的冷门书源撑起来的。现在就打开编辑器写下你的第一行search吧。【免费下载链接】read-cat一款免费、开源、简洁、纯净、无广告的小说阅读器项目地址: https://gitcode.com/gh_mirrors/re/read-cat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ReadCat 书源插件极简上手：写 3 个方法，跑通从搜索到正文的完整阅读链路
ReadCat 书源插件极简上手写 3 个方法跑通从搜索到正文的完整阅读链路【免费下载链接】read-cat一款免费、开源、简洁、纯净、无广告的小说阅读器项目地址: https://gitcode.com/gh_mirrors/re/read-cat晚上十一点你在阅读器里搜一本冷门小说弹出的却是结果为空和半屏广告。这种体验ReadCat 想彻底终结——它是一款免费、开源、简洁、纯净、无广告的小说阅读器而它的在线内容全部来自书源插件也就是由你这样的开发者用代码定义去哪找书、怎么解析。这篇教程会带你从零写出第一个真正能用的书源跑通搜索、详情、正文三个环节全程约 20 分钟。先解决一个实际问题为什么 ReadCat 坚持用插件把书源做成插件就像浏览器把能力交给扩展核心只管阅读体验去哪找书完全外包。好处很明显——网站改版了你更新插件就行不必等客户端发版不想用的站点随时禁用。ReadCat 默认不携带任何书源首次使用时空空如也但这恰恰是它干净的原因内容来源由你掌控。先别急着理解全部原理。照着下面做让一个假书源先跑起来你会立刻明白三个方法在阅读器里各自扮演什么角色。跑通第一个最小示例让 ReadCat 认识你的书源新建一个my-first-source.js粘贴下面这段代码class MyFirstSource { static ID myfirstsource20260813001; static TYPE 0; static GROUP 我的测试; static NAME 我的第一个书源; static VERSION 1.0.0; static VERSION_CODE 1; static PLUGIN_FILE_URL ; static BASE_URL https://example.com; constructor({ request, cheerio, store }) { this.request request; this.cheerio cheerio; this.store store; } async search(searchkey) { return [{ bookname: 测试小说, author: 佚名, detailPageUrl: https://example.com/book/1 }]; } async getDetail(detailPageUrl) { return { bookname: 测试小说, author: 佚名, coverImageUrl: , intro: 一本用于学习的测试书, chapterList: [{ title: 第一章, url: https://example.com/book/1/c1, index: 0 }] }; } async getTextContent(chapter) { return [这是正文的第一段。, 这是正文的第二段。]; } } plugin.exports MyFirstSource;这段代码做了什么先说静态属性——它们是插件的身份证ReadCat 导入时会逐一校验ID必须是 16 到 32 位的字母数字组合TYPE用 0 表示书源1 是书城2 是朗读引擎NAME和GROUP各限制在 15 个字符内BASE_URL必须以 http 或 https 开头。这些规则全部写在src/core/plugins/index.ts的校验逻辑里。构造函数里ReadCat 会注入三件套request网络请求、cheerioHTML 解析用法和 jQuery 一致、store键值缓存。随后实现三个核心方法search返回搜索结果列表getDetail返回详情和章节数组getTextContent返回正文段落数组。最后用plugin.exports导出类这是沙箱约定的出口。保存后打开 ReadCat 的「设置 → 插件」点导入按钮选中这个文件启用它再去搜索页随便搜个关键词——测试小说真的出现了。一个能搜、能进详情、能翻正文的完整书源就这样跑通了。三个方法对应阅读器的三次动作现在原理已呼之欲出一次阅读行为本质就是三次方法调用。search(searchkey)对应搜书动作返回SearchEntity列表核心字段是bookname、author、detailPageUrl。getDetail(detailPageUrl)对应打开详情页动作必须返回chapterList章节数组每章带title、url、index。getTextContent(chapter)对应翻开正文的动作返回一个字符串数组每个元素是一段。另外要注意ReadCat 会在你返回正文后自动做一次 HTML 消毒sanitizeHTML把脚本和垃圾标签过滤掉——这一点在踩坑环节还会遇到。接入真实网站请求、解析与乱码假书源跑通后把硬编码数据换成真实请求即可。请求统一走注入的this.request.get跨域问题已经替你处理好了async search(searchkey) { const { body } await this.request.get( ${MyFirstSource.BASE_URL}/search?q${encodeURIComponent(searchkey)}, { charset: UTF8, headers: { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) } } ); const $ this.cheerio.load(body); return $(.book-item).map((i, el) ({ bookname: $(el).find(.name).text().trim(), author: $(el).find(.author).text().trim(), detailPageUrl: $(el).find(a).attr(href), })).get(); }charset用于指定网页编码——国内不少站点仍是 GBK读错了就是满屏乱码headers里带上正常的User-Agent能降低被反爬拦截的概率。getDetail和getTextContent套路相同请求 URL →cheerio.load解析 → 提取字段返回。请求配置支持的全部参数见src/core/request/defined/request.d.ts。踩坑实录新手最容易翻车的四个场景导入时报Property not found。大概率是静态属性拼错或ID位数不在 16 到 32 之间对照校验规则逐项检查即可。正文全是乱码。把charset从UTF8改成GBK同理提交参数的编码urlencode也要和站点保持一致。能搜到书正文却为空。常见原因是正文由 JavaScript 动态渲染静态 HTML 里根本没有或是返回内容被消毒逻辑过滤成了空串。前者去换一个能拿到数据的接口后者检查正文是否藏在script或iframe标签里。请求被网站拒绝。先补全headers仍不行可在请求配置里加proxy: true再到设置里开启代理——ReadCat 的请求层对代理支持得很完整。进阶一步开发调试、缓存与自动更新别再用改代码 → 重新导入的笨办法了。ReadCat 在设置里内置了插件开发工具导入官方工具包、配置端口后点「启动」即可在浏览器里热调试插件相关代码在src/core/plugin-devtools/与electron/plugin-devtools.ts。调试稳定后有三件事值得做一是用store.setStoreValue / getStoreValue缓存搜索结果减少重复请求二是给PLUGIN_FILE_URL填上插件文件的在线地址用户就能通过「更新」按钮一键升级网站改版时不必挨个通知三是用 try/catch 兜住请求失败的场景给出友好提示而不是让阅读器抛一屏红色堆栈。下一步把插件变成你的作品从最小示例到真实书源你已经走完了插件开发 90% 的路。剩下 10% 是细节目录去重、分页加载、封面图处理、不同站点的差异兼容。想参考完整实现内置的 Edge TTS 朗读引擎src/core/plugins/built-in/tts/edge.ts就是一份活教材接口定义在src/core/plugins/defined/booksource.d.ts插件的存储与状态管理在src/store/plugins.ts。想深入参与可以git clone https://gitcode.com/gh_mirrors/re/read-cat拉取源码边看边改。写出的第一个书源哪怕只是为某个冷门站点做了适配也值得分享给社区——开源项目的生命力正是由一个个没人愿意做的冷门书源撑起来的。现在就打开编辑器写下你的第一行search吧。【免费下载链接】read-cat一款免费、开源、简洁、纯净、无广告的小说阅读器项目地址: https://gitcode.com/gh_mirrors/re/read-cat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考