本地漫画导入怎么做才顺手：扫描、解析与格式兼容的取舍

做漫画阅读器这几年，我发现一个反直觉的事：用户最常抱怨的不是在线源加载慢，而是本地漫画导不进来，或者导进来了却乱成一团。文件夹里明明躺着几百本漫画，阅读器一扫只认出一半，剩下的要么没封面，要么标题是乱码，要么同一本出现三四次。本地导入看着是“读个目录”的小功能，实际是文件系统、压缩格式、编码和数据库四件事搅在一起，处处都是取舍。

我维护的 Venera-Next 是一款免费无广告的 Flutter 跨平台漫画阅读器，本地漫画是它的基本盘之一。下面这几组取舍，都是我在这块踩过坑之后定下来的。

取舍一：全量扫描还是增量扫描

最省事的写法是每次打开本地书架就全量扫一遍目录：递归遍历、逐个文件算哈希、比对数据库。这个写法我第一版就是这么做的，几十本漫画时毫无感觉，等用户导入上千本、其中还有几个 GB 的大压缩包，打开书架要卡十几秒。问题不在遍历本身，而在每次都要对大文件做 IO，还要解压包头读元数据。

我现在的策略是增量为主、全量为辅。数据库里存每个已导入文件的路径、大小、修改时间和一个轻量指纹（文件头几 KB 加文件尾的哈希，而不是整文件哈希，算得快、误判率也够低）。启动时只做目录遍历，对比路径和修改时间：没变过的文件直接跳过，只处理新增、删除和修改过的文件。全量校验只在用户手动点“重新扫描”时才跑一次。

这里有个坑：只靠修改时间判断会漏掉一种情况——用户用某些同步工具（比如 WebDAV 同步）覆盖文件后，修改时间可能被保留成旧值，内容却变了。我的折中办法是再加一个文件大小比对，大小和时间都一样才跳过；大小变了就重新解析。两次比对的成本几乎可以忽略，漏判概率降到可以接受。

还有一个细节：扫描一定要在后台 isolate 里跑，不要阻塞 UI 线程。Flutter 里文件 IO 是异步的，但解压包头、算哈希这类 CPU 活如果放在主 isolate，列表滚动会肉眼可见地掉帧。我把扫描任务拆成批次，每扫完 50 个文件就回主线程更新一次进度条，用户能看到“正在扫描 123/800”而不是盯着转圈发呆。

取舍二：压缩包格式到底支持多少种

本地漫画最常见的载体是 CBZ（本质是 ZIP）和 CBR（本质是 RAR），另外还有直接以文件夹形式存放的图片序列。理想状态是全支持，现实是每个格式都是一笔维护债。

ZIP 是最友好的：Dart 生态有纯 Dart 实现，不用调原生代码，跨平台零成本，读取包内文件列表很快。我把它作为一级支持，封面提取、章节图片读取都走这条路。

RAR 就麻烦得多。Dart 没有成熟的纯 Dart RAR 解压库，要支持就得接原生库，Android、iOS、Windows、Linux、macOS 每个平台都要单独处理，包体积和崩溃率都会涨。我最后的决定是：桌面端通过系统已装的解压能力或可选的外部工具兜底，移动端明确不支持 CBR，只在导入时给一句清楚的提示，告诉用户转成 CBZ 再导入。与其半吊子支持一个到处崩的格式，不如把不支持说清楚，让用户一次就明白。

文件夹形式的图片序列反而最容易被低估：它没有压缩包头，扫描时要逐个文件判断是不是图片，还要处理隐藏文件（macOS 的 .DS_Store、Windows 的 Thumbs.db）、嵌套子目录（有人把“第一卷/第 1 话/001.jpg”套三层），以及文件名排序问题。“第 10 话”排在“第 2 话”前面，是字符串排序的经典坑，我的做法是解析文件名里的数字做自然排序，解析不到数字的回落到字符串排序，并且允许用户在设置里切换排序规则。

编码是另一个暗坑。ZIP 包里的文件名编码可能是 UTF-8，也可能是 GBK 或 Shift-JIS，尤其是从日文站点下载的老包。我遇到过整包文件名全是乱码的情况。我的处理是：先按 UTF-8 解，失败再试 GBK 和 Shift-JIS，逐个候选解码，选第一个能正常显示的；全部失败才显示原始字节转义后的名字，并允许用户手动重命名。完美解决不了，但能把乱码率压到很低。

取舍三：元数据解析，解析多少才够用

导入时除了文件本身，还要解析出标题、作者、封面、章节数这些元数据。解析得越全，书架越好看；解析得越多，导入越慢。这里我分了两级。

第一级是导入时必须立刻拿到的：标题（默认用文件夹名或压缩包名）、封面、总页数。封面提取是关键性能点：不能把整包解出来再找封面，那样大包导入会慢到不可接受。我的做法是只读 ZIP 中央目录，定位到第一张图片，只解那一张做封面；文件夹形式则只读排序后的第一张图。封面解出来后立刻生成一张小尺寸缩略图存进缓存，原图不常驻内存，列表滚动只用缩略图。

第二级是延迟解析的：作者、简介、标签、章节切分。这类信息有的藏在压缩包附带的 ComicInfo.xml 里，有的根本不存在。我不把它们放在导入主流程里，而是导入完成后在后台慢慢补：先让书能看、能上架，再逐步丰富信息。解析到 ComicInfo.xml 就用里面的，解析不到就留空，不阻塞、不报错。

还有一个容易被忽略的点：重复导入。用户可能同一个漫画既有文件夹版又有 CBZ 版，或者换了个目录重新导入一遍。我的去重逻辑是：先按归一化标题（去掉空格、括号内容、全半角统一）加总页数做第一轮匹配，疑似重复的再比对文件指纹，确认重复后提示用户是保留两者还是只留一个，而不是静默地吞掉或静默地复制一份。静默处理最省事，但用户发现书架里少了一本时，永远不知道是被吞了还是没导进来。

结论

本地导入这个功能，拼的不是支持多少格式，而是每一处“不知道”都给用户一个明确的交代：扫到一半能看到进度，不支持的格式说清楚原因，乱码了给重命名的入口，重复了让用户自己选。导入流程里我最看重的一条原则是：先让书能上架、能打开，再慢慢补信息；先保证不丢书、不重复，再谈书架好不好看。

这些取舍最后都落到了 Venera-Next 的本地导入实现里。如果你也在做类似的本地内容管理工具，或者正被自己漫画库的导入问题困扰，希望这篇里的几个坑能帮你少走点弯路。