novel-downloader 3.0.0

A command-line tool for downloading Chinese web novels from Qidian and similar platforms.

novel-downloader

异步小说下载工具 / 库。支持断点续爬、广告过滤、多格式导出, 并提供 CLI 与 Web 图形界面。

运行要求: Python 3.11+ (开发环境: Python 3.13)

功能特性

下载能力

• 可恢复下载: 自动识别已完成的章节, 跳过重复抓取
• 可插拔式 HTTP 后端: 支持 aiohttp (默认)、httpx、curl_cffi

多格式导出

• TXT
• EPUB
• HTML

内容清洗与增强

• 广告与活动过滤
  • 章节标题过滤
  • 正文章节过滤
• 文本处理流水线 (processors)
  • 正则清理
  • 繁简转换
  • 机器翻译
• 图片章节 / 混淆章节处理 (image-utils 可选)
  • 原图下载
  • 去水印
  • 图像预处理
  • 图片章节转文字 (需要 enable_ocr)
  • 字体混淆还原 (需要 enable_ocr)

扩展性

• 插件系统: 可扩展站点解析、文本处理器、导出器等能力
• 可插拔式下载后端: 适配不同 HTTP 客户端

使用方式

• 命令行 (CLI)
• Web 图形界面 (GUI)

---

安装与更新

使用 pip 安装最新稳定版本:

pip install -U novel-downloader

如需启用字体解密 / 图片转文字 (enable_ocr), 请参见: 安装

---

快速开始

0. 设置语言 (可选)

# 设置为中文
novel-cli config set-lang zh_CN

# 设置为英文
novel-cli config set-lang en_US

1. 初始化配置文件

# 生成默认配置 ./settings.toml
novel-cli config init

生成 settings.toml 后可编辑 request_interval、book_ids 等参数。

详见: settings.toml 配置说明

2. 命令行 (CLI)

常用示例:

# 使用书籍页面 URL 自动解析并下载
novel-cli download https://www.hetushu.com/book/5763/index.html

# 使用配置文件中的 book_ids 启动下载
novel-cli download --site qidian

# 指定站点 + 书籍 ID 启动下载
novel-cli download --site n23qb 12282

更多参数:

novel-cli --help
novel-cli download --help

• 支持站点见: 支持站点列表
• 更多示例见: CLI 使用示例
• 运行中可使用 CTRL+C 取消任务

3. 图形界面 (Web GUI)

Web GUI 依赖额外组件 (如 NiceGUI), 默认不会随主程序一起安装。

如需使用 Web 图形界面，请先安装对应的可选依赖。

3.1. 安装 Web GUI 依赖

pip install novel-downloader[web-ui]

若只需使用 CLI，可忽略此步骤。

3.2 启动 Web GUI

novel-web

如需提供局域网/外网访问 (请自行留意安全与网络环境):

novel-web --listen public

在运行过程中, 可使用 CTRL+C 停止服务。

3.3 更多资料

• 支持站点见: 支持站点列表
• 更多示例见: WEB 使用示例

4. 编程接口 (Programmatic API)

import asyncio
from novel_downloader.plugins import registrar
from novel_downloader.schemas import BookConfig, ClientConfig

async def main() -> None:
    site = "n23qb"

    # 指定书籍 ID
    book = BookConfig(book_id="12282")

    # 创建客户端
    cfg = ClientConfig(request_interval=0.5)
    client = registrar.get_client(site, cfg)

    # 在异步上下文中执行下载
    async with client:
        await client.download(book)

    # 下载完成后执行导出操作
    client.export(book, formats=["txt", "epub"])

if __name__ == "__main__":
    asyncio.run(main())

---

文本处理 (processors)

导出前可执行多阶段流水线处理, 包括:

• 正则清理 (自定义去广告/去水印)
• 繁简转换 (基于 opencc-python)
• 自动翻译 (支持 google / edge / youdao 等翻译器)
• 文本纠错 (基于 pycorrector)

处理顺序可配置, 并可生成中间产物用于导出

详细配置示例见: processors 配置

---

插件系统

通过插件可扩展站点解析、文本处理器、导出器等能力。

在 settings.toml 启用插件并实现对应接口后, 即可自动加入下载流程。

示例: 新增站点解析器 (如 "刺猬猫" -> ciweimao), 实现目录页与章节页的抓取及解析方后即可直接下载:

novel-cli download --site ciweimao 123456

详见: 插件系统文档

---

从源码安装 (开发版)

git clone https://github.com/saudadez21/novel-downloader.git
cd novel-downloader

# 可选: 为多语言支持编译翻译文件
# pip install babel
# pybabel compile -d src/novel_downloader/locales

pip install .
# 或安装带可选功能:
# pip install .[image-utils]

---

常见问题 / 排错

• 网站结构变更导致解析失败: 请更新至最新版或按站点文档自定义适配。
• 需要登录的站点: 参考 复制 Cookies。
• 导出文件位置: 见 文件保存。

---

注意事项

• 站点结构变更: 若目标站点页面结构更新或章节抓取异常, 欢迎提 Issue 或提交 PR
• 登录支持范围: 登录功能受站点策略与接口限制, 部分场景需要手动配置 Cookie 或进行账号绑定
• 请求频率: 请合理设置抓取间隔, 避免触发风控或导致 IP 限制

---

文档导航

• 安装
• 配置
• settings.toml 配置说明
• 支持站点列表
• CLI 使用示例
• WEB 使用示例
• 复制 Cookies
• 文件保存
• 模块与接口文档
• TODO

---

项目说明

• 本项目仅供学习和研究使用, 不得用于任何商业或违法用途; 请遵守目标网站的 robots.txt 及相关法律法规
• 使用本项目产生的任何法律责任由使用者自行承担, 作者不承担相关责任