当前位置：首页 > news >正文

深度解析novel-downloader规则扩展架构：3步实现自定义网站支持

news 2026/6/8 19:33:03

深度解析novel-downloader规则扩展架构：3步实现自定义网站支持

【免费下载链接】novel-downloader一个可扩展的通用型小说下载器。项目地址: https://gitcode.com/gh_mirrors/no/novel-downloader

novel-downloader作为一个高度可扩展的通用小说下载器，其核心价值在于模块化的规则扩展系统。通过深入理解其架构设计和实现原理，开发者可以快速为任意小说网站添加支持，显著提升下载器的覆盖范围。本文将从技术架构、规则实现到实际案例，全面解析novel-downloader的规则扩展机制。

架构设计与核心组件

novel-downloader采用分层架构设计，将核心下载逻辑与网站特定规则分离。主要组件包括：

基础规则类（BaseRuleClass）：位于src/rules.ts，定义了所有规则必须实现的抽象接口，包括书籍解析bookParse()和章节解析chapterParse()方法。该类封装了并发控制、错误处理、缓存管理等通用功能。

规则模板系统：提供mkRuleClass()工厂函数，位于src/rules/onePage/template.ts，简化单页式网站的规则创建。开发者只需提供DOM选择器和处理函数，即可快速生成完整的规则类。

类型化规则目录：项目按网站结构特征分类组织规则：

onePage/：单页式小说网站（章节内容在同一页面）
twoPage/：双页式网站（目录与内容分离）
special/：特殊处理网站（需要登录、验证码等）
lib/：通用工具库和共享组件

图：novel-downloader规则架构展示，包含基础规则类、模板系统和类型化规则目录

规则实现的技术细节

1. 书籍元数据提取

书籍解析的核心是准确提取书名、作者、简介和封面信息。以52shuku规则为例：

export const i52shuku = () => mkRuleClass({ bookUrl: document.location.href, bookname: ( document.querySelector("h1.article-title") as HTMLElement )?.innerText.trim(), author: "", introDom: document.querySelector("article.article-content > p:nth-of-type(2)") as HTMLElement, coverUrl: null, aList: document.querySelectorAll("ul.list > li.mulu > a"), // ... 其他配置 });

关键参数说明：

bookUrl：当前页面URL，用于标识书籍来源
bookname：使用CSS选择器定位书名元素
introDom：简介DOM元素，支持自定义处理函数
aList：章节链接列表，支持复杂选择器

2. 章节内容提取策略

内容提取需要考虑网站特定的DOM结构和反爬机制。novel-downloader提供多种内容处理模式：

基础内容提取：使用getContent()函数定位正文区域：

getContent: (doc) => doc.querySelector("#nr1") as HTMLElement,

内容清理与标准化：通过contentPatch()函数处理提取的内容：

contentPatch: (content) => { // 移除多余广告元素 rm("div", true, content); // 替换链接为纯文本 const links = content.querySelectorAll("a"); links.forEach(link => { link.replaceWith(document.createTextNode(link.textContent || "")); }); return content; },

多页内容合并：对于分页显示的内容，使用nextPageParse()函数自动合并多个页面。

图：小说章节内容提取过程，展示从原始HTML到清理后内容的转换

3. 并发控制与反爬策略

针对不同网站的访问限制，规则可以配置并发参数：

// 52shuku使用Cloudflare，严格限制并发 concurrencyLimit: 1, sleepTime: 50,

并发控制机制：

concurrencyLimit：同时下载的最大章节数
sleepTime：单线程模式下的请求间隔基数
maxSleepTime：最大等待时间，防止触发反爬

实战：3步创建自定义规则

步骤1：分析目标网站结构

首先使用浏览器开发者工具分析网站DOM结构：

定位书名和作者信息的选择器
识别章节链接的容器和选择器
确定正文内容的选择器
检查是否需要处理分页或特殊元素

图：使用开发者工具分析小说网站DOM结构，识别关键元素选择器

步骤2：选择规则模板并实现

根据网站类型选择合适的模板目录：

单页式网站（onePage）：

// 在src/rules/onePage/目录下创建新文件 import { mkRuleClass } from "./template"; import { rm } from "../../lib/dom"; export const mySiteRule = () => mkRuleClass({ bookUrl: document.location.href, bookname: document.querySelector(".book-title")?.textContent?.trim(), author: document.querySelector(".author-name")?.textContent?.trim(), introDom: document.querySelector(".book-intro") as HTMLElement, aList: document.querySelectorAll(".chapter-list a"), getContent: (doc) => doc.querySelector(".chapter-content") as HTMLElement, contentPatch: (content) => { // 清理广告和无关元素 rm(".advertisement", false, content); return content; }, concurrencyLimit: 5, sleepTime: 100, });

双页式网站（twoPage）：需要分别实现目录页和内容页的解析逻辑，使用twoPage目录下的模板。

特殊网站（special）：处理需要登录、验证码、字体加密等复杂情况，参考src/rules/special/中的实现。

步骤3：注册规则并测试

在src/rules.ts中导入并注册新规则：

import { mySiteRule } from './rules/onePage/mySite'; // 在rules数组中添加新规则 const rules = [ // ... 现有规则 mySiteRule(), ];

测试新规则：

在浏览器中访问目标网站
运行novel-downloader脚本
检查控制台日志和下载结果
使用test/e2e-validate.ts进行自动化验证

高级特性与最佳实践

1. 章节去重与重排序

novel-downloader内置章节处理工具：

deDuplicate()：自动去重重复章节
reIndex()：重新编号章节顺序
chapterHiddenFix()：修复隐藏或无效的章节链接

2. 图片附件处理

支持智能图片下载和缓存：

import { getAttachment } from "../../lib/attachments"; // 封面图片处理 getAttachment(coverUrl, this.attachmentMode, "cover-") .then((coverClass) => { additionalMetadate.cover = coverClass; });

3. 自定义清理选项

通过cleanDomOptions配置DOM清理行为：

cleanDomOptions: { removeTags: ["script", "style", "iframe"], keepTags: ["p", "br", "img"], keepAttributes: ["src", "alt"], }

图：DOM清理前后对比，展示广告移除和格式标准化效果

4. 错误处理与日志

完善的错误处理机制：

自动重试失败的请求
详细的调试日志输出
用户友好的错误提示
支持自定义错误回调

性能优化与扩展建议

并发策略优化

根据目标网站特点调整并发参数：

高防网站：concurrencyLimit: 1-2,sleepTime: 200-500ms
宽松网站：concurrencyLimit: 5-10,sleepTime: 50-100ms
动态调整：基于响应时间自动调整并发数

缓存机制利用

novel-downloader内置多级缓存：

会话级映射缓存（SessionMappingCache）
图片附件缓存
DOM解析结果缓存
本地存储过期管理

扩展点设计

项目提供多个扩展点供高级用户使用：

自定义章节过滤器（chapterFilter）
自定义保存选项（saveOptions）
自定义完成回调（customFinishCallback）
自定义附件处理模式

测试与调试技巧

开发环境配置

本地测试：使用开发服务器运行规则测试
日志级别：调整日志级别获取详细调试信息
断点调试：在浏览器开发者工具中设置断点
网络监控：观察请求频率和响应时间

自动化测试

编写测试用例确保规则稳定性：

// 在test/sites.ts中添加测试 { name: "MySite", url: "https://mysite.com/book/123", rule: mySiteRule, test: async (page) => { // 验证书籍信息提取 // 验证章节列表获取 // 验证内容提取质量 } }

图：novel-downloader测试界面，展示规则验证和调试功能