THE READING GUIDE
本地漫画导入
从文件夹、压缩包、PDF 或图片型 EPUB 开始阅读。
英文版本:import_comic.en.md
简介
VeneraPlus 支持从本地目录、漫画压缩包、PDF 和图片型 EPUB 导入漫画。导入后的内容会统一存放为本地图片漫画,以复用现有阅读模式、进度记录和拆分双页等能力。
本地漫画位于 书库 -> 本地漫画。导入后的漫画可直接在此集中浏览、排序与阅读。
支持的漫画图片扩展名包括 jpg、jpeg、jpe、png、webp、gif 和 avif。
恢复本地下载
如果迁移应用时保留了本地下载文件夹,但丢失了 local.db,可以通过扫描当前本地路径恢复本地数据库。
- 打开
书库->本地漫画-> 顶栏导入->恢复本地下载。 - 应用会扫描当前本地存储路径并重建条目。
- 该操作不会复制文件,也不会添加收藏。
- 同名标题或目录会被视为重复并跳过。
执行前请确认「设置 → 存储与同步」中的本地存储路径指向包含已下载漫画的目录。
漫画目录
目录只有符合以下两种结构之一时,才会被视为漫画目录。
无章节目录
comic_directory
├── cover.[ext]
├── img1.[ext]
├── img2.[ext]
├── img3.[ext]
├── ...
包含章节目录
comic_directory
├── cover.[ext]
├── chapter1
│ ├── img1.[ext]
│ ├── img2.[ext]
│ ├── img3.[ext]
│ ├── ...
├── chapter2
│ ├── img1.[ext]
│ ├── img2.[ext]
│ ├── img3.[ext]
│ ├── ...
├── ...
图片文件名可以任意命名,但扩展名必须是有效图片格式。
页面顺序由文件名决定。应用会按文件名排序后按顺序显示。
封面图是可选的。如果目录中存在 cover.[ext],它会被识别为封面;否则第一张图片会被用作封面。
漫画标题使用漫画目录名。章节标题使用章节目录名。
压缩包
VeneraPlus 支持从压缩包导入漫画。
压缩包适合作为导入、导出、归档、迁移和分发格式,应符合 Comic Book Archive 格式。
当前支持以下压缩包格式:
.cbz.cb7.zip.7z
压缩包可以直接包含图片,也可以包含一个顶层目录;如果顶层目录下是多个章节目录,应用会按章节目录导入。
猫之眼[北条司].cbz
└── 猫之眼[北条司]
├── cover.jpg
├── 第01卷
│ ├── 001.jpg
│ └── 002.jpg
└── 第02卷
├── 001.jpg
└── 002.jpg
如果根目录没有 cover.[ext],应用会使用第一章的第一张图片作为封面。
漫画归档与恢复
本地漫画菜单中的归档上传、归档页面中的下载导入会逐本显示结果、远端文件名和失败详情。可单独重试某项、重试全部失败项或继续未开始项目,成功项不会重复操作;取消会等待当前操作安全结束。关闭结果窗口后不保留本轮结果与重试记录。
WebDAV 上传使用条件请求避免覆盖同名文件,首次发现同名时显示「跳过(未核验)」。上传结果不确定后重试,会下载同名远端文件并核对本次上传内容,可能增加流量与临时空间;内容不一致时保留冲突。其他网盘沿用对应服务的写入能力。导入可能已经入库而结果无法确认时,会禁用直接重试,应先检查本地漫画库。
更改本地存储目录时会暂停下载,复制完成并保存漫画库引用和任务路径后再清理旧目录;提交后中断或清理失败会保留有效的新漫画库,并在下次启动恢复。
PDF 与图片型 EPUB
在 书库 -> 本地漫画 -> 顶栏 导入 中可以分别选择 PDF 漫画文件或图片型 EPUB 文件。这两种格式都会在导入时转换为应用管理的本地图片漫画,而不是直接读取原文件。
- 在
书库->本地漫画-> 顶栏导入->PDF 漫画文件中可一次选择一个或多个 PDF;每个文件分别导入为一本漫画,收藏夹只需选择一次。 - 后台任务管理:PDF 导入作为应用级任务在后台队列中串行执行。发起导入后,用户可随时关闭进度弹窗、返回上层或阅读其他漫画,导入不会被中断。用户可在
书库->本地漫画页面(顶栏任务按钮或窄屏更多菜单)重新打开任务面板查看进度,任务完成不会抢占当前导航。 - 取消与安全清理:点击取消会停止后续排队文件(排队任务直接释放,不进入准备阶段);当前正在渲染或写入的文件在安全结束后会清理未完成的临时目录。已成功导入入库的漫画完整保留,不会被误删或撤销。
- 会话边界与退出限制:导入任务仅在当前应用运行会话内有效。导入期间请保持应用运行,不支持应用退出或进程杀死后跨重启自动续传。Android 上无法直接访问的文件会逐本准备临时副本,处理完成后立即释放。
- 存储迁移与目录所有权互斥保护:
- 后台导入在渲染与入库期间受到存储保护锁(
LocalStorageGuard)保护,在此期间会拒绝存储路径迁移(setNewPath)与本地下载扫描恢复;反之,若存储迁移正在进行,PDF 导入会安全等待其完成。 - 导入会话在生成漫画目录前先同步创建并占用唯一的专属目录标记,防止与并发的同名 CBZ 归档恢复、目录拷贝或其他任务发生目录冲突;单项任务取消或失败时仅清理自身专属目录,绝不误删其他任务的数据。
- 后台导入在渲染与入库期间受到存储保护锁(
- 每个 PDF 页面会按顺序渲染为 JPEG 图片,第一页同时作为封面。
- 导入结果是无章节的单本漫画,标题默认使用 PDF 文件名。
- 为兼顾清晰度、内存和存储占用,页面按约 3 倍 PDF 点尺寸渲染,最长边限制为 3000 像素。
- 加密或需要密码的 PDF 暂不支持。
- 导入会生成新的图片副本,因此需要预留额外本地存储空间。
图片型 EPUB
- 支持 spine 中直接引用栅格图片,或 XHTML/SVG 页面通过
img、SVGimage引用栅格图片的固定版式 EPUB。 - 页面顺序以 EPUB spine 为准;元数据中的标题、作者和封面会尽量保留。
- 当 EPUB 导航中存在多个有效章节时会保留章节;没有明确章节导航时会导入为无章节漫画。
- 原始栅格图片会直接复制,不重新压缩。
- 文字型 EPUB、直接绘制的 SVG 页面、外部图片引用和越界路径会被拒绝,不会静默丢弃正文。
当前不支持 MOBI、AZW 和 AZW3。它们是电子书容器而不是本项目当前的图片漫画交换格式,建议先在外部工具中转换为图片型 EPUB、PDF 或 CBZ。
如果本地漫画库中已经存在同名作品,文档导入不会覆盖原内容。
WebDAV 与网盘在线漫画库
在线漫画库是独立于本地导入导出和漫画归档备份的阅读渠道,可通过 WebDAV 或已配置的网盘账号访问。
在线阅读支持远端图片目录、单本 ZIP/CBZ、图片型 EPUB 和 PDF。目录漫画按需列目录和加载图片;ZIP/CBZ 与图片型 EPUB 可直接按需读取包内图片,无须先解压到服务端;PDF 则按原始页码渲染所需页面。VeneraPlus(或旧版 VeneraNext)导出的单本 CBZ 可保留标题、作者、标签和章节信息,EPUB 则读取 OPF 书籍元数据与导航。账号与目录设置见多网盘存储。
阅读器会按当前生效的“预加载张数”提前加载并解码后续页面,同时准备前一页,优先准备距离当前页较近的页面。该设置在翻页、连续和瀑布流阅读中一致生效,并沿用设备及单本漫画的设置覆盖规则。云端 PDF 同一轮所需的文件分段可并行读取,仍共用账号的限速队列。
“WebDAV 漫画库”设置中的“同步漫画库配置”开关默认关闭。启用后,DataSync/Appdata 的 .venera 数据会包含漫画库地址、用户名、密码、远程路径、自动更新开关和更新间隔;接收设备也必须在本地启用该开关才会导入这些字段。凭据会存储在远程 .venera 文件中,只应在可信的 WebDAV 和账号上启用。
普通目录模式
推荐结构:
/venera_comics/
└── 猫之眼[北条司]
├── cover.jpg
├── 第01卷
│ ├── 001.jpg
│ └── 002.jpg
└── 第02卷
├── 001.jpg
└── 002.jpg
普通目录模式的规则:
- 漫画标题取漫画文件夹名。
- 子目录作为章节;如果根目录直接包含图片,则根目录图片可作为单章节漫画阅读。
- 页面和章节按文件名排序,推荐使用补零编号,例如
0001.jpg、0002.jpg。 - 封面优先使用根目录下文件名为
cover的图片;支持jpg、jpeg、png、webp、gif、jpe、avif。没有独立封面时,依次使用根目录首图、首个可读章节的cover.*或首图。 - 不要求
metadata.json或ComicInfo.xml。
Bangumi 自动刮削
连接 Bangumi 并在设置中开启“自动刮削”(默认关闭)后,同步 WebDAV 漫画库时会为缺少 metadata.json 的漫画自动搜索条目。识别结合当前作品标题、目录名和成员文件名;只使用扫描或按需解析已经取得的信息,不为刮削提前打开所有 EPUB、PDF 或压缩包。图片目录的章节尚未检查时保留待处理状态,取得章节文件名后再确认是否未匹配。
搜索前会反复清理首尾已知的类别、语言、版本和汉化注记,包括 (成年コミック)、[雑誌]、[中国翻訳]、[無修正]、[DL版] 和 汉化者:[汉化名],并提取 作者:[北条司]、著者:【北条司】 等明确作者提示。[作者][作品]卷01_p001_img001.png 可提供作品名与待核实的作者;没有明确含义的括号内容仍保留为完整标题候选。卷/话编号、页码和 .kepub.epub 等文件格式信息不作为作品名。去掉单字母或编号目录前缀,以及使用额外的父目录名时,需要成员文件名或已确认作者提供佐证;同一卷的重复图片名不会增加可信度。
清洗后的标题必须与 Bangumi 中文名、原名或明确别名精确对应,支持全半角字符和中文简繁变体;日文原名保留假名与长音。作者提示必须匹配条目信息框,或人物接口中的作者、原作、作画等创作关系,汉化组、社团或出版社不能仅凭名称被认定为作者。不同成员书名互相冲突时不自动写入。每部作品最多搜索 3 个不同关键词、读取 5 个候选详情;候选仍有歧义或检查数量不足以确认唯一条目时保留未匹配。
杂志会保留刊名及完整年月号,例如 COMIC BAVEL 2026年7月号,不能用刊物总条目或其他期号代替。仅有作者及 pixivFANBOX 的发布合集、含义不明的缩写不会被猜测为某部作品,来源站点的数字编号也不会作为 Bangumi Subject ID。
Nedpy_01.pdf 这类没有明确卷/话单位的编号文件名只提供弱提示,不推断缩写的含义,也不会覆盖已经明确的作品名。
匹配成功后,应用以仅新建的条件请求写入 UTF-8 metadata.json,不会覆盖同步期间由其他客户端创建的文件。标题优先使用 Bangumi name_cn,为空时使用 name;简介使用条目详情的 summary;作者来自条目信息框或人物接口;标签由全部官方 meta_tags 与按 count 降序排列的前 10 个用户标签合并去重。WebDAV 账号必须拥有漫画目录写权限。自动刮削不会覆盖任何已经存在的 metadata.json,也不会下载 Bangumi 封面。未匹配(noMatch)状态按作品在本地持久化,同一规则版本下不会因重新打开、重启、加载封面或分卷、普通同步、强制同步或文件变动而重复搜索;规则版本更新后可重新尝试,网络失败则按退避时间重试。
连接 Bangumi 后,可在云端漫画详情页点击右上角「⋯ → 重新刮削元数据」,为当前作品重新搜索,即使全局“自动刮削”已关闭也可使用。未找到可靠条目时显示“未找到匹配”并继续保留该状态,匹配成功后刷新当前详情。已有元数据时跳过刮削;需要纠正已有信息时,可手动绑定 Bangumi 条目。聚合作品统一使用作品级刮削结果,打开成员卷不会单独搜索或生成成员旁车。
连接 Bangumi 后,漫画库扫描或打开详情时检测到有效的 bangumiSubjectId,会在后台自动建立阅读进度绑定,图片目录、分卷作品及文件旁车沿用各自的元数据归属。自动绑定使用“自动”话/卷解析,不回写元数据,也不会覆盖已有绑定或主动上传历史章节进度;已有远端进度、评分和收藏状态会保留,没有远端收藏时创建“想读”。该功能不要求开启自动刮削;后续阅读上传仍受“自动同步”开关控制。未连接或请求失败时,下次扫描或打开详情可再次尝试,包括从缓存读取元数据。若保留元数据中的 ID,解除绑定后再次扫描或打开详情仍会自动绑定。
用户在漫画详情页手动绑定 Bangumi 条目时,该条目被视为明确选择。手动绑定完成后会立即结束前台加载,应用再在后台读取条目详情并更新 WebDAV 漫画的 title、author、description、tags 和 bangumiSubjectId;即使新值为空,也会清除旧的错误字段。写入前会读取最新版元数据,以 ETag 或 Last-Modified 条件更新,并在并发冲突后重新合并;合法的 chapters 页码范围和未知扩展字段会保留。服务器不给现有文件提供任一校验器时,应用会拒绝不安全的覆盖。临时失败会连同漫画库、漫画和条目身份保存在本地队列中,并在启动或退避时间到达后重试;如果配置或绑定已变化,旧任务不会写入新漫画库。后台写入失败不会撤销已经成功的进度绑定。
Bangumi 绑定按漫画库身份隔离;身份由规范化的服务地址、用户名和远程根路径组成,不包含密码,因此只更新密码不会丢失绑定,而切换服务器、账号或根路径不会复用旧库中同路径漫画的绑定。将状态改为“读过”时,应用会重新读取远端收藏与条目总话数/总卷数,一次提交两个进度维度;远端已有的更高进度和用户明确输入的更高值都不会被降低。
元数据标记的分层目录模式
如果 WebDAV 目录层级较深,建议在漫画根目录放置 metadata.json,将该文件夹明确标记为一本漫画:
/venera_comics/
└── 分类/
└── 作者/
└── 猫之眼/
├── metadata.json
├── cover.jpg
├── 第01章/
│ ├── 001.jpg
│ └── 002.jpg
└── 第02章/
└── 001.jpg
应用会在同步 WebDAV 漫画库时递归查找带有 metadata.json 的目录,并将该目录作为一本漫画;其直接子目录作为章节。找到漫画根目录后不会继续把章节或更深层目录单独识别为漫画。漫画 ID 使用相对于 WebDAV 漫画库路径的目录路径,因此不同分类下的同名漫画不会互相覆盖。
在这种模式下,漫画标题、作者、简介和标签来自 metadata.json,章节名称和章节路径来自直接子目录。根目录下的 cover.* 只作为封面;如果根目录还有普通图片,它们会作为 Images 章节保留。
当目录同时存在真实章节文件夹和 metadata.json 中的 chapters 页码范围时,真实章节文件夹优先,页码范围不会被强行映射到文件夹。只有根目录图片、没有章节文件夹时,chapters[].start 和 chapters[].end 才用于扁平 CBZ 目录的虚拟分章。
同步会在受限深度和目录数量内递归发现未标记的多层漫画:包含普通根目录图片的目录会直接视为漫画。WebDAV 漫画库优先通过 metadata.json 和目录内容判断漫画边界:metadata.json 是最明确的漫画标记,拥有最高优先级,子目录中的元数据不会被章节名称规则绕过;若某目录没有根目录图片且无元数据,当其直接叶子子目录均符合章节命名时,这些子目录会被视为该漫画的章节,父目录被识别为漫画根目录。如果分类目录下直接放置多本仅包含图片的扁平漫画,由于其与“漫画根目录 + 多章节”在文件结构上同构,应用会结合章节名称特征进行消歧,不像章节的子目录仍会作为独立漫画发现。所有模式下均会验证章节是否包含有效图片,空子目录或仅含封面图的目录不会作为可阅读章节展示,也不会被误选为漫画封面。若因网络故障读取失败或达到最大递归深度/扫描目录数量上限,应用将停止推断并保留上一次成功同步的目录索引,绝不提交残缺或揣测的错误目录索引。对于复杂或容易歧义的目录结构,推荐在每本漫画根目录添加 metadata.json。
如果旧版本曾将章节目录错误识别为独立漫画,并在章节目录内自动生成了
metadata.json,需要手动删除这些错误的章节级metadata.json后重新同步,应用不会自动删除远端元数据文件。
CBZ 解压增强模式
VeneraPlus(及旧版 VeneraNext)导出的单本 CBZ 解压后通常是扁平图片目录:
/venera_comics/
└── 猫之眼
├── metadata.json
├── ComicInfo.xml
├── cover.jpg
├── 0001.jpg
├── 0002.jpg
├── 0003.jpg
└── 0004.jpg
metadata.json 模板:
{
"title": "猫之眼",
"author": "北条司",
"description": "三姐妹经营咖啡店并寻找父亲失踪真相的故事。",
"tags": ["动作", "漫画"],
"chapters": [
{"title": "第01卷", "start": 1, "end": 2},
{"title": "第02卷", "start": 3, "end": 4}
],
"bangumiSubjectId": 123456
}
字段规则:
| 字段 | 类型 | 说明 |
|---|---|---|
title |
字符串 | 漫画标题;空字符串会回退为文件夹名 |
author |
字符串 | 作者,可为空字符串 |
description |
字符串 | 漫画简介,可为空字符串;Bangumi 刮削时来自条目详情的 summary |
tags |
字符串数组 | 漫画标签,可为空数组 |
bangumiSubjectId |
正整数或 null |
对应的 Bangumi Subject ID;自动刮削或手动绑定时写入 |
chapters |
数组或 null |
章节范围;为 null 或空数组时,根目录图片作为单章节 |
chapters[].title |
字符串 | 章节显示名称,不可为空 |
chapters[].start |
整数 | 章节起始页,从 1 开始,包含该页 |
chapters[].end |
整数 | 章节结束页,包含该页 |
章节范围必须按顺序排列、不得重叠、不得反向,并且不能超过根目录实际页面数。cover.* 不计入页面编号。元数据允许存在额外字段,以便后续扩展;当前不会从元数据读取远端 URL、脚本或本地绝对路径。
metadata.json 使用 UTF-8 编码,文件名匹配不区分大小写。ComicInfo.xml 会随 CBZ 导出保留,用于其他漫画阅读器兼容;VeneraPlus WebDAV 漫画库当前以 metadata.json 为增强信息来源。
如果元数据文件缺失,连接 Bangumi 后会先按上述保守规则尝试自动刮削;无法匹配时回退普通目录模式。如果文件已经存在但无法读取、JSON 损坏、字段类型错误或章节范围不合法,自动刮削不会覆盖该文件,漫画仍会按可解析内容或普通目录模式显示。用户明确绑定 Bangumi 条目后,若文件仍是可解析的 JSON 对象,条件合并可以修复标题、作者、简介和标签,并尽量保留结构合法的 chapters;无法解析的文件不会被静默替换。
这里的 metadata.json 是单本 CBZ 的元数据格式,不是 .venera-comics 批量导出包中的漫画列表格式,两者不可混用。
ZIP/CBZ、图片型 EPUB 与 PDF 云端按需阅读
将 .zip、.cbz、图片型 .epub 或 .pdf 放入在线漫画库配置的识别目录后,单个文件可作为一本漫画,同目录下有共同书名和分卷编号的文件会聚合为一本作品。ZIP/CBZ 内可以直接放图片,也可以包含一个顶层目录或章节目录;可选的单本漫画 metadata.json 沿用上述字段和章节范围规则。EPUB 的阅读顺序和章节由书籍结构与导航决定,PDF 按原始页码读取并渲染。
图片目录与 ZIP/CBZ、图片型 EPUB、PDF 可以混排。漫画目录中的归档独立显示,不会把该漫画或它的章节改成分类目录。例如,书名目录下同时有 cover.png、同名 ZIP 和 全1卷/ 时,图片版仍以书名为标题、以 全1卷 为章节,ZIP 另列为一本漫画。总页数按实际正文图片统计,封面和归档不计入图片目录页数;尚未扫描的章节会在打开详情时补齐。
/venera_comics/
├── 猫之眼.cbz
│ └── 猫之眼/
│ ├── metadata.json
│ ├── cover.jpg
│ ├── 第01卷/
│ │ ├── 001.jpg
│ │ └── 002.jpg
│ └── 第02卷/
│ └── 001.jpg
└── 另一部漫画.zip
├── 0001.jpg
└── 0002.jpg
ZIP/CBZ 与 EPUB 按需读取归档尾部和中央目录,再读取元数据及所需图片条目。封面在需要显示时加载并缓存,阅读页面也复用图片缓存,无须预先下载或解压整个归档。
多文件分卷与版本
同一目录下,例如 作品 第01卷.epub、作品 第02卷.pdf、作品 第03卷.cbz,会按共同书名聚合为一本作品,各文件作为一卷。格式不同不影响连续阅读。卷、话、章及范围会保留各自含义;Nedpy_01.pdf 这样的纯编号文件保留原名并自然排序,不会凭数字猜测卷或话。不同书名或不同作品目录中的文件不会仅因格式相同而合并。
作品目录下可使用明确的格式/版本子目录,例如:
/venera_comics/作品/
├── EPUB格式/
│ ├── [作品]卷01.epub
│ └── [作品]卷02.epub
└── PDF台版/
├── 作品_01.pdf
└── 作品_02.pdf
上述结构只显示一本作品,详情和阅读器通过章节分组切换版本。连续阅读、自动阅读和跨卷预加载只在当前版本内进行;可以通过章节选择显式切换到另一版本。同卷有多个文件时也会保留为不同版本,不会自动删除或把重复卷串接起来。带 metadata.json 的作品目录可以明确指定聚合边界及作品信息。
扫描和打开作品详情只建立成员卷列表,不会先解析所有 EPUB、PDF 或压缩包;打开某卷或加载封面时才解析对应文件。未解析卷不显示猜测的页数,已解析索引和图片缓存可以复用。聚合作品以文件为阅读卷,卷内保持 EPUB spine、PDF 原页码或 ZIP/CBZ 的页面顺序;独立文件漫画仍可使用其原生章节。
目录作品的标题、作者、简介和 Bangumi 信息使用作品根目录的 metadata.json;平铺目录中按共同书名聚合的作品使用 书名.metadata.json。成员文件自己的完整文件名旁车继续只描述该文件。作品级 chapters 页码范围不跨成员文件分章,分卷列表来自成员文件。
图片型 EPUB
应用通过 META-INF/container.xml 定位 OPF,按 OPF manifest 与 spine 的阅读顺序展开正文,不会按图片文件名排序。支持 spine 直接引用光栅图片,以及静态 XHTML 的 img、SVG 包装页的 image 对本书图片的引用;同一文档包含多张图片时按文档顺序展开,同图在 spine 中重复出现时保留其位置,跳过 linear="no" 的非正文项与空白页。
EPUB 3 的 nav 目录或 EPUB 2 的 NCX 中有多个有效章节标记时,按对应 spine 文档边界建立阅读章节;“第 001 页/頁”“Page 001”等页码导航及生成器署名不用于分章,没有明确分章时提供整份文件的连续阅读入口,不按图片数量猜测分章。优先使用 OPF 声明的封面;明确的封面页不会再重复计入正文,没有封面声明时使用首张正文图。标题、作者、简介和标签优先读取 OPF 的基础书籍信息,可由旁车字段覆盖。
首次解析只读取必要的 container、OPF、导航和 XHTML/SVG 控制文档,读取这些条目时不预取相邻图片。相邻的正文控制文档会合并读取,减少逐页请求造成的首次打开等待,合并范围不会跨过图片或未使用的条目。封面及正文图片在显示时才加载,并复用同一账号的限速队列、范围缓存和图片缓存。文字型 EPUB、带正文文字或脚本及复杂排版的页面、直接绘制的 SVG、DRM/加密内容均不支持;外链图片、data: 图片和越出书籍范围的路径会被拒绝,不会静默丢弃文字或转为整包下载。
支持普通可打开的 PDF,包括图片、文字和矢量页面;应用渲染页面内容,不抽取包内图片。阅读顺序和总页数保持 PDF 的原始页码,第 1 页既作为封面,也保留为正文第 1 页。标题缺省使用文件名,当前不自动读取 PDF 内嵌标题或作者,可通过旁车或手动绑定 Bangumi 补充。
有多个指向不同有效页面的 PDF 书签时,按目标页建立章节;首个书签之前的封面或前言页仍保留。没有可用分章时提供“全1卷”入口。同级 Book.pdf.metadata.json 可覆盖书名、作者等字段或指定从 1 开始的章节范围,范围对应原始 PDF 页码,包含首页。例如,16 页 PDF 可写入:
{
"title": "漫画",
"chapters": [
{"title": "封面与前言", "start": 1, "end": 2},
{"title": "第一章", "start": 3, "end": 16}
]
}
打开时按需读取文档结构与书签,渲染时准备目标页所需的数据;支持非线性化 PDF,只渲染请求的页面,不预先渲染整本。渲染沿用本地 PDF 导入标准:按原尺寸放大 3 倍、最长边不超过 3000 像素,再编码为质量 92 的 JPEG,并复用账号读取队列、范围缓存和图片缓存。
当前不支持加密或需要密码的 PDF,不执行 PDF JavaScript。文件服务同样必须支持 HTTP Range;读取或渲染失败时明确报错,不自动下载整份 PDF。
网络读取失败或取消时会安全结束当前任务;索引损坏、需要完整下载才能修复的 PDF 会明确报错。
ZIP/CBZ 卷/话目录
归档详情始终提供可点击的阅读目录。旁车或包内元数据中的合法 chapters 页码范围优先;没有显式分章时,按包内图片目录自然排序。第01卷/第01话/ 这类多层目录按上层路径分组显示,章节按钮同时显示正文页数。
单独一层 全1卷/、第03卷/ 等明确的卷/话目录会保留其名称。图片直接平铺,或只套有书名文件夹时,采用归档文件名中明确的卷/话标识;没有这类信息则显示“全1卷”。根目录散页与其他章节共存时,散页保留为“图片”章节。显示分组不改变原有章节顺序、图片标识和阅读位置。
已经平铺的多话漫画可通过旁车显式分章,无须重新打包。例如,80 页正文可在 漫画.cbz.metadata.json 中写入:
{
"chapters": [
{"title": "第01话", "start": 1, "end": 32},
{"title": "第02话", "start": 33, "end": 64},
{"title": "番外", "start": 65, "end": 80}
]
}
页码从 1 开始,对应自然排序后的正文图片,排除 cover.*。仅有连续数字图片名或 Bangumi 总话数时,不会按固定页数猜测章节边界。
归档旁车元数据
ZIP/CBZ、图片型 EPUB 和 PDF 可在同级目录使用 UTF-8 JSON 旁车文件,命名为“完整文件名 + .metadata.json”,保留 .zip、.cbz、.epub 或 .pdf 扩展名。例如:
/venera_comics/
├── Book.zip
├── Book.zip.metadata.json
├── Book.cbz
├── Book.cbz.metadata.json
├── Book.epub
├── Book.epub.metadata.json
├── Book.pdf
├── Book.pdf.metadata.json
└── Book/
├── metadata.json
└── 001.jpg
Book.zip.metadata.json、Book.cbz.metadata.json、Book.epub.metadata.json 和 Book.pdf.metadata.json 分别属于对应的文件漫画;图片目录 Book/metadata.json 继续只描述该目录,各文件不会混用。
旁车是 JSON 对象,字段类型与上面的单本漫画元数据格式相同,也允许只填写部分字段:
{
"title": "猫之眼",
"bangumiSubjectId": 123456
}
读取时,旁车中类型及范围合法的字段优先;省略的字段继续使用 ZIP/CBZ 包内 metadata.json、EPUB 的 OPF 基础元数据或 PDF 的可用书签章节,因此只修改标题不会丢失已有作者、标签或章节。
chapters 页码仍从 1 开始:ZIP/CBZ 使用自然排序并排除 cover.* 独立封面,EPUB 使用 spine 顺序并排除显式封面页,PDF 使用包含首页的原始页码。作为默认封面的首张正文图仍计入正文。范围必须有序、不重叠且不超出实际页数。没有旁车时继续兼容原有元数据;缺少标题时回退文件名,EPUB 和 PDF 的页面顺序仍分别以 spine 与原始页码为准。
连接 Bangumi 并开启自动刮削后,ZIP/CBZ、图片型 EPUB 和 PDF 会在按需检查、确认旁车与内嵌元数据都缺失时,以文件名及已取得的作品命名信息搜索;目录扫描不会为此读取整个包。分卷聚合作品仅使用属于该作品的成员信息,不混用同级其他作品。匹配规则沿用上面的保守匹配方式,匹配成功后仅新建对应的同级旁车文件。
在 ZIP/CBZ、图片型 EPUB 或 PDF 详情页手动绑定 Bangumi 时,标题、作者、简介、标签和条目标识写入对应的同级旁车,包括 Book.epub.metadata.json 和 Book.pdf.metadata.json。应用不会重新打包归档、重写 PDF 或改写包内 metadata.json、OPF;新文件使用仅新建请求,更新已有旁车时继续使用 ETag 或 Last-Modified 条件保护,并保留合法章节范围和未知扩展字段。临时失败沿用后台重试队列,失败不会撤销成功的进度绑定。账号需要拥有旁车所在目录的写权限。
范围读取与缓存
同一网盘账号下的漫画库共用归档读取队列:最多同时执行 4 个请求,请求启动间隔至少 150 毫秒,当前阅读页优先于封面和预读;预读页成为当前页时会提升已有请求的优先级。收到 HTTP 429 后,队列遵守 Retry-After 统一冷却;缺失或无效时按 1、2、4 秒退避,一次范围读取最多重试两次。等待中的读取可取消。
翻页阅读优先预解码后续两页和前一页,后续页数不超过设置的预加载数量;剩余预加载范围只缓存图片文件。预加载数量遵循单本漫画、设备和全局设置的优先级。
ZIP/CBZ 与 EPUB 的小图片条目会将本地头与压缩数据合并到对齐的范围请求中,单次合并读取不超过 2 MiB;同一账号使用总计 16 MiB 的内存范围缓存复用相邻条目,较大图片仍精确按需读取。这样能减少请求突发和零碎读取,具体网盘的账号或 IP 限制仍以服务端规则为准。
远端文件服务必须实际支持 HTTP Range,并返回正确的分段响应;仅能列出文件或声明支持 Range 并不足够。若服务器忽略 Range、返回整包或提供无效范围,应用会明确报错,不会隐式改为整包下载。网盘直链、代理或重定向后的文件服务也须满足这一要求。
底层 ZIP/ZIP64 容器支持 Store(不压缩)和 Deflate 压缩方式,拒绝加密、分卷及其他压缩方式。7z/CB7 不能直接在线阅读,可先在服务端解压为图片目录。归档备份与恢复仍是独立能力。
图片型 EPUB 与 PDF 尚未完成各平台及真实网盘的端到端实测;ZIP/CBZ 的已有验证结果仅适用于其已验证场景,不代表其他格式也已验证。具体存储服务的 Range 兼容性须以实际响应为准。