novel-downloader：一个可扩展的通用型小说下载器技术深度解析

novel-downloader：一个可扩展的通用型小说下载器技术深度解析

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

novel-downloader 是一款基于浏览器扩展技术的开源小说下载工具，采用模块化架构设计，支持超过200个小说网站的内容提取与格式转换。该项目通过创新的三层解码机制和灵活的规则系统，解决了网络小说因平台限制、内容下架等问题导致的阅读障碍，为技术爱好者和阅读者提供了强大的离线阅读解决方案。

技术背景与核心问题分析

在数字阅读时代，网络小说平台的内容管理策略各异，部分作品可能因版权变更、平台政策调整或技术故障而突然下架。传统下载工具往往面临以下技术挑战：

1. 网站结构多样性：不同小说平台采用不同的HTML结构和CSS选择器
2. 反爬虫机制：包括图片文字替换、动态加载、验证码等技术手段
3. 内容格式复杂性：图文混排、章节分页、VIP付费墙等复杂场景
4. 浏览器环境限制：需要在不破坏用户体验的前提下实现批量下载

novel-downloader 通过浏览器脚本技术直接在用户端运行，避免了服务器端代理的延迟和带宽限制，同时通过本地处理保障了用户数据隐私。

架构设计与核心组件解析

模块化规则引擎

项目的核心在于其模块化的规则系统，位于src/rules/目录下。规则系统按照网站类型进行分类：

• 单页小说规则(src/rules/onePage/)：处理章节内容在同一页面的网站
• 多页小说规则(src/rules/twoPage/)：处理章节分页显示的网站
• 特殊站点规则(src/rules/special/)：处理有特殊需求的主流平台

每个规则文件继承自BaseRuleClass抽象基类，实现两个核心方法：

// 基础规则类定义 export abstract class BaseRuleClass { public abstract bookParse(): Promise<Book>; public abstract chapterParse( chapterUrl: string, chapterName: string | null, isVIP: boolean, isPaid: boolean | null, charset: string, options: Record<string, any> ): Promise<ChapterParseObject>; }

三层解码机制

针对图片文字替换的反爬策略，项目实现了创新的三层解码方案：

1. 文件名映射解码器(src/lib/decoders/FilenameDecoder.ts)：通过图片文件名快速匹配对应文字
2. 哈希映射解码器(src/lib/decoders/HashDecoder.ts)：计算图片哈希值进行精确匹配
3. OCR识别解码器(src/lib/decoders/OCRDecoder.ts)：使用PaddleOCR模型识别图片中的文字

图：novel-downloader 的OCR解码引擎工作流程，展示图片文字识别与匹配过程

OCR解码器采用ONNX运行时和PaddleOCR模型，支持在浏览器端进行本地文字识别：

// OCR解码器核心实现 export class OCRDecoder { private readonly cacheKey = "paddleocr_ch_models"; private readonly cacheVersion = "4.0.0-v5-mobile"; async decode(imageData: Uint8Array): Promise<OCRResult | null> { await this.ensureModelLoaded(); const imageDataObj = await this.uint8ArrayToImageData(imageData); const result = await this.ocrEngine.ocr(imageDataObj); // 提取置信度最高的识别结果 if (result && result.parragraphs && result.parragraphs.length > 0) { let bestResult = result.parragraphs[0]; for (const paragraph of result.parragraphs) { if (paragraph.mean && paragraph.mean > (bestResult.mean || 0)) { bestResult = paragraph; } } const cleanText = bestResult.text .trim() .replace(/\s+/g, "") .replace(/[^\u4e00-\u9fff\u3400-\u4dbf\u3000-\u303f\uff00-\uffef]/g, ""); return { text: cleanText.charAt(0), confidence: bestResult.mean || 0 }; } return null; } }

内容处理流水线

小说内容处理遵循清晰的流水线架构：

1. 网页解析阶段：通过DOM操作提取书籍元数据和章节列表
2. 内容下载阶段：并发下载章节内容，支持断点续传
3. 数据处理阶段：清理HTML、解码图片文字、提取附件
4. 格式转换阶段：生成TXT、EPUB等格式文件

图：novel-downloader 的章节解析与内容提取界面，展示批量下载队列管理

配置与部署指南

环境准备与安装

项目作为油猴脚本运行，安装过程简洁：

1. 安装浏览器脚本管理器（Tampermonkey、Violentmonkey等）
2. 获取最新版脚本文件
3. 脚本管理器自动检测并提示安装

核心配置参数

在src/setting.ts中，用户可以调整多项运行时参数：

// 核心配置示例 export const concurrencyLimit = 10; // 并发下载线程数 export const sleepTime = 50; // 章节下载间隔基数（毫秒） export const maxSleepTime = 500; // 最大间隔时间 export const enableDebug = false; // 调试模式开关 export const TxtDownload = true; // 是否生成TXT格式 export const EpubDownload = true; // 是否生成EPUB格式

网站适配配置

对于需要特殊处理的网站，项目提供了灵活的配置选项。以晋江文学城为例：

// 晋江文学城特殊配置 const tokenOptions = { Jjwxc: { token: "your_token_here", user_key: "your_user_key_here" } };

高级功能与扩展开发

自定义章节筛选

用户可以通过自定义筛选函数实现精确的章节选择：

// 自定义章节筛选示例 function chapterFilter(chapter) { // 只下载前100章 if (chapter.chapterNumber <= 100) return true; // 只下载包含特定关键词的章节 if (chapter.chapterName.includes("武器")) return true; // 排除VIP章节 if (chapter.isVIP && !chapter.isPaid) return false; return false; }

输出格式定制

通过自定义保存参数，用户可以完全控制输出文件的样式和内容：

const saveOptions = { // 自定义章节标题格式 getchapterName: (chapter) => { return `第${chapter.chapterNumber}章 ${chapter.chapterName}`; }, // 调整段落样式 mainStyleText: `p { text-indent: 2em; line-height: 1.8; margin: 0.5em 0; }`, // 删除空行 genChapterEpub: (contentXHTML) => { return contentXHTML.replaceAll("<p><br /></p>", ""); } };

图：novel-downloader 解析后的章节内容展示，保留原始排版格式

扩展新网站支持

为新的小说网站添加支持只需创建对应的规则文件。以单页小说为例：

// 新建网站规则示例 import { mkRuleClass } from "./template"; export default mkRuleClass({ bookUrl: "https://example.com/novel/123", bookname: "示例小说", author: "示例作者", coverUrl: "https://example.com/cover.jpg", // 章节列表选择器 aList: document.querySelectorAll(".chapter-list a"), // 内容提取函数 getContent: (doc) => { return doc.querySelector(".content"); }, // 内容清理选项 cleanDomOptions: { removeTags: ["script", "style", "iframe", "ins"], keepOnlyTags: ["p", "h1", "h2", "h3", "h4", "h5", "h6", "img"], removeAttrs: ["style", "class", "id"] }, // 并发限制 concurrencyLimit: 5, sleepTime: 100 });

性能优化与最佳实践

并发控制策略

项目通过精细的并发控制避免对目标网站造成过大压力：

// 并发控制实现 export class BaseRuleClass { public concurrencyLimit = 10; public sleepTime = 50; public maxSleepTime = 500; protected async downloadChapters(chapters: Chapter[]) { return concurrencyRun( chapters, async (chapter) => { await this.downloadChapter(chapter); await sleep(this.sleepTime); }, this.concurrencyLimit ); } }

缓存机制优化

为提高重复下载效率，项目实现了多层缓存机制：

1. 图片缓存：通过ImageCache类缓存已下载的图片资源
2. 会话映射缓存：使用SessionMappingCache缓存URL到内容的映射
3. OCR模型缓存：将PaddleOCR模型缓存在本地存储中

错误处理与调试

项目提供了完善的错误处理和调试机制：

1. 调试模式：启用后生成详细的debug.log文件
2. 进度监控：通过右下角进度条实时显示下载状态
3. 控制台日志：F12控制台输出详细的下载过程信息

图：novel-downloader 处理图文混排内容的展示效果，图片与文字正确解析

技术展望与社区贡献

架构演进方向

当前架构支持以下技术演进：

1. 智能解析增强：引入机器学习模型自动识别网站结构
2. 分布式下载：支持多浏览器实例协同下载大型作品
3. 云同步集成：与云存储服务集成实现多设备同步

社区贡献指南

项目采用开放的贡献模式，开发者可以通过以下方式参与：

1. 添加新网站支持：参考现有规则文件编写适配代码
2. 优化现有规则：改进解析算法或修复已知问题
3. 功能扩展：添加新的输出格式或处理功能

贡献流程遵循标准Git工作流：

git clone https://gitcode.com/gh_mirrors/no/novel-downloader cd novel-downloader # 开发新功能或修复问题 git commit -m "功能描述" git push origin feature-branch

技术挑战与解决方案

项目面临的主要技术挑战包括：

1. 动态内容加载：通过模拟用户交互和等待策略处理
2. 验证码识别：依赖用户手动输入或第三方服务
3. 内容加密保护：分析JavaScript代码实现解密逻辑

资源保护与合理使用

项目设计遵循以下原则：

1. 尊重版权：仅下载已购买或合法获取的内容
2. 合理使用：个人阅读使用，不进行商业传播
3. 技术研究：作为网页解析和内容提取的技术参考

总结

novel-downloader 通过创新的技术架构解决了网络小说下载中的多个技术难题。其模块化规则系统、三层解码机制和灵活的配置选项，为技术爱好者和普通用户提供了强大的工具支持。项目不仅具有实用价值，也为网页内容提取、反爬虫应对等技术领域提供了有价值的参考实现。

随着数字阅读生态的不断发展，此类工具在保护数字文化遗产、应对平台限制方面将发挥越来越重要的作用。开源社区的共同建设确保了项目的持续演进和技术创新，为更多用户带来便捷的阅读体验。

图：novel-downloader 生成的TXT格式文件，展示结构化章节层级和内容提取质量

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