ReadCat书源插件开发实战15分钟写出你的第一个可用书源插件【免费下载链接】read-cat一款免费、开源、简洁、纯净、无广告的小说阅读器项目地址: https://gitcode.com/gh_mirrors/re/read-cat在 ReadCat 里搜书名却弹出一句没有可用的书源这种憋屈相信不少人经历过。书源插件开发就是解决这个问题的钥匙——ReadCat 本身不生产内容它靠插件从你指定的网站搬运小说。别被开发两个字吓到这篇教程会用最直白的方式带你从零写出第一个能跑的 ReadCat 书源插件全程约 15 分钟。一、新手最爱问的三个问题先答为敬Q1书源插件到底是什么一句话一段 JS 代码负责告诉 ReadCat 三件事——去哪儿搜书、书的详情长啥样、章节正文怎么抓。ReadCat 的插件体系全部集中在src/core/plugins/目录你要打交道的主要是里面三份文件defined/booksource.d.ts书源插件的接口定义一切规范的源头booksource.ts书源插件的体检逻辑缺方法直接报错index.ts插件加载、校验、运行的核心管理类。Q2我需要多强的编程基础会写最基础的 JavaScript认识async/await就够了。不会 CSS 选择器也没关系用正则也能解析。ReadCat 已经在沙箱里替你准备好了request、cheerio、store这些工具你只管调用。Q3书源插件和书城、语音引擎有什么区别ReadCat 的插件分三类用枚举值区分0书源、1书城、2语音引擎。书城管逛书架式的推荐页语音引擎管朗读而书源管搜索详情正文这也是日常使用频率最高的一类。本文只聊书源。二、先看清体检表一个书源插件的最低要求ReadCat 导入插件时不是随便跑的它会先做一轮严格校验相当于给插件体检。书源插件必须满足两条硬规矩规矩一类上必须声明齐全静态属性。校验代码在src/core/plugins/index.ts的_isPlugin方法里逐项核对 ID、TYPE、GROUP、NAME、VERSION、VERSION_CODE、PLUGIN_FILE_URL、BASE_URL缺一个、格式不对一个直接拒绝导入。几个最容易踩的雷ID长度必须在16~32 位之间且只能含字母、数字、下划线和连字符NAME和GROUP长度1~15个字符不能有首尾空格PLUGIN_FILE_URL如果不填就得是合法的http(s)://xxx.js格式BASE_URL对书源是必填项且必须以http(s)://开头。规矩二三个核心方法一个都不能少。booksource.ts里的isBookSource会逐一检查search、getDetail、getTextContent是否都存在、是不是函数缺一个就抛Function [xxx] not found。这三个方法的名字是固定的少写、写错拼写插件都活不了。三、手写第一个最小书源插件完整代码纸上谈兵没意思直接上能跑的骨架。新建一个my-first-source.js把下面代码贴进去class MyFirstSource { // ---- 静态属性给插件上户口 ---- static ID my_first_source_2024; // 16~32位 static TYPE 0; // 0 书源 static GROUP 我的插件; static NAME 我的第一个书源; static VERSION 1.0.0; static VERSION_CODE 1; static PLUGIN_FILE_URL ; static BASE_URL https://example.com; // 目标站点 // ---- 构造函数接住 ReadCat 递过来的工具箱 ---- constructor(config) { this.request config.request; // 发请求用的 this.cheerio config.cheerio; // 解析 HTML 用的 this.store config.store; // 存数据的 } // 方法一搜索 async search(keyword) { const res await this.request.get( ${MyFirstSource.BASE_URL}/search?q${encodeURIComponent(keyword)} ); const $ this.cheerio.load(res.body); const list []; $(.book-item).each((i, el) { list.push({ bookname: $(el).find(.name).text().trim(), author: $(el).find(.author).text().trim(), coverImageUrl: $(el).find(img).attr(src), detailPageUrl: $(el).find(a).attr(href), latestChapterTitle: $(el).find(.last).text().trim(), }); }); return list; } // 方法二详情 async getDetail(detailPageUrl) { const res await this.request.get(detailPageUrl); const $ this.cheerio.load(res.body); const chapterList []; $(.chapter-list a).each((i, el) { chapterList.push({ title: $(el).text().trim(), url: $(el).attr(href), index: i, }); }); return { bookname: $(.book-name).text().trim(), author: $(.book-author).text().trim(), coverImageUrl: $(.cover img).attr(src), intro: $(.intro).text().trim(), chapterList, }; } // 方法三正文 async getTextContent(chapter) { const res await this.request.get(chapter.url); const $ this.cheerio.load(res.body); const paragraphs []; $(.content p).each((i, el) { paragraphs.push($(el).text().trim()); }); return paragraphs; } }这段代码里静态属性对应上文的体检表三个方法对应接口文档src/core/plugins/defined/booksource.d.ts里的定义。把它保存好你已经有第一个插件雏形了。四、三大方法逐个拆解返回值格式是成败关键很多人写插件感觉代码没问题却不出结果九成是返回值格式没对齐。ReadCat 的期望格式定义在src/core/book/book.d.ts里我帮你翻译成人话search(keyword)→ 返回搜索结果数组每个结果是一个对象只有bookname书名和author作者是必填coverImageUrl封面、detailPageUrl详情页链接、latestChapterTitle最新章节名是可选的。注意detailPageUrl一定给全链接别只给相对路径否则点进详情页时 ReadCat 无从拼接。getDetail(detailPageUrl)→ 返回一个详情对象比搜索多了intro简介和chapterList章节列表。chapterList里每一项是{ title, url, index }index是章节序号从 0 开始数别漏了。getTextContent(chapter)→ 返回字符串数组chapter就是详情阶段存下来的那个章节对象。返回值必须是段落字符串组成的数组ReadCat 拿到后会逐段渲染。如果你返回一整坨带大量空行的字符串阅读界面会很难看。 小技巧正文里通常混着换行符和广告尾巴在组装数组前先用.replace(/\s/g, )之类做一次清洗效果立竿见影。五、写完了怎么导入、怎么调试导入打开 ReadCat 的设置 → 插件点导入选中你的.js文件即可。导入逻辑在src/store/plugins.ts对应的界面 hooks 里本质是调用GLOBAL_PLUGINS.importJSCode导入失败会把每个插件的报错原因列成清单弹给你看——认真读报错90% 的问题都能自己定位。调试这是 ReadCat 很贴心的设计。它自带一个插件开发工具代码在electron/plugin-devtools.ts和src/core/plugin-devtools/能单独对search、getDetail、getTextContent逐个点菜试跑每次调用返回什么、报什么错一目了然完全不用反复改完再导入。调试期记得保持插件开启改完代码重新导入即可生效。六、避坑清单这些坑我都替你踩过了按出现频率排个序写插件时对照着自查ID 长度不够 16 位——最隐蔽的报错ID 随手写个test1必挂返回值结构不对——search少给detailPageUrl、getTextContent返回了字符串而不是数组都是高频错误编码问题——部分站点是 GBK 编码中文全变乱码请求时带上charset参数图片防盗链——封面图加载不出来考虑在请求里带Referer头站点改版——昨天还能解析的页面今天结构变了插件就会失灵这是常态维护插件本质是维护解析规则存储空间有限——每个插件的store上限 4MB见src/core/plugins/index.ts里的常量别把大对象往里面塞正文被消毒——ReadCat 会对正文做 HTML 清洗sanitizeHTML并过滤空串所以别依赖原样输出解析时自己先做规范。七、下一步从能跑到好用第一版能跑只是及格线。想让插件真正好用建议依次做三件事加错误兜底try/catch包住每个方法站点抽风时返回空数组而不是让整个搜索崩掉支持翻页搜索结果多时ReadCat 支持分页加载你的search若能识别下一页参数体验直接上一个台阶分享出去把插件分享给朋友或按自己的阅读习惯做搜索增强让书源插件开发真正为你服务。写第一个插件的过程本质上就是读懂一个网站的过程。去翻一个你常看的书站把它的页面结构对照本文骨架改一改——很快你就会发现全网小说都尽在掌握了。动手吧别让没有书源再拦住你【免费下载链接】read-cat一款免费、开源、简洁、纯净、无广告的小说阅读器项目地址: https://gitcode.com/gh_mirrors/re/read-cat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考