看漫工具（Kanman Reader）

一款面向 Android 与 macOS 的本地漫画阅读器，专门优化超长条漫和大型 ZIP/CBZ 漫画包。

普通图片查看器打开超长漫画时，往往会先把整张图片缩小到窗口内，阅读者需要反复手动放大。看漫工具默认让漫画铺满当前窗口宽度，并保持原始比例连续向下阅读。

当前版本：1.3.1+25

主要功能

阅读体验

• 打开漫画后自动铺满当前窗口宽度
• 支持单张超长图和文件夹多图连续阅读
• 支持双指缩放、双击缩放和屏幕缩放按钮
• Android 与 macOS 首页均使用封面书架展示最近阅读
• macOS 支持空格、Page Up/Down、Home/End、Command G 跳转和 Command +/-/0 缩放
• 自动记录页码与本页阅读位置
• 支持按页码和本页百分比精确跳转
• 明亮、暗色两套界面

文件格式

• 图片：JPG、JPEG、PNG、WebP、GIF、BMP
• 漫画包：未加密 ZIP、CBZ
• 压缩包内图片按文件名自然排序
• 支持文件夹递归读取，并自动忽略隐藏文件

大型漫画包

压缩包大小	读取策略
小于 1 GB	全量解压，适合连续快速阅读
大于等于 1 GB	按需提取当前页，降低磁盘占用和启动压力

• Android 与 macOS 都会先显示低清分块底图，再对屏幕附近区域加载高清分块
• 阅读页提供“省内存 / 平衡 / 更流畅”三种预加载策略
• Android 根据设备内存动态设置图片缓存，范围约为 128–256 MB
• 只保留最近两个章节的缓存，可在应用内查看和清理占用
• 缓存页解码失败时会尝试从原压缩包自动修复

数据安全

• 全程本地离线阅读，不上传漫画内容
• 检查 ZIP 路径穿越、加密条目、单文件大小和解压总量
• 解压时验证 ZIP 条目 CRC，避免损坏内容进入缓存
• 诊断日志默认只记录文件名和路径哈希，不包含图片内容
• 支持导出诊断包，便于分析偶发的页面加载问题

快速开始

环境要求

• Flutter SDK（项目当前使用 Dart ^3.12.2）
• Android Studio、Android SDK、JDK 17
• 构建 macOS 版本需要完整 Xcode

获取依赖并验证

flutter pub get
dart analyze
flutter test

构建 Android APK

flutter build apk --release

生成文件：

build/app/outputs/flutter-apk/app-release.apk

未配置 android/key.properties 时，项目会使用适合个人安装测试的 debug 签名。正式分发时应配置自己的 release keystore。

构建 macOS App

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license
sudo xcodebuild -runFirstLaunch
flutter build macos --release

生成文件：

build/macos/Build/Products/Release/看漫工具.app

项目结构

lib/
├── models/       漫画来源、阅读进度和偏好设置
├── reader/       统一阅读位置、布局映射和预加载协调器
├── services/     导入、ZIP 索引、缓存、日志和性能策略
├── ui/           首页、阅读页和主题
└── utils/        文件名自然排序等工具

android/          Android 原生区域解码与平台配置
macos/            macOS 区域解码、拖放和平台配置
third_party/      为大型本地文件读取适配的 file_picker
test/             导入、缓存、阅读进度和界面测试

实现说明

• UI 使用 Flutter Material 构建，Android 与 macOS 共用主要业务代码
• ZIP/CBZ 使用中央目录索引，超过阈值后无需一次性把整个压缩包载入内存
• 页码、总进度、页内位置和跳转共用同一套阅读位置及布局模型
• 超长图片在原生层按可视区域分为低清预览与高清显示两级解码
• 最近阅读的图片清单保存在应用支持目录，SharedPreferences 只保存轻量索引和设置
• 缓存统计、批量清理和大批文件校验在后台 Isolate 中执行

当前限制

• 暂不支持 CBR、RAR、7Z
• 暂不支持加密 ZIP/CBZ
• 原始文件被移动或删除后，只能继续阅读已经缓存的页面
• 超过 8 GB 的单个压缩包会被安全限制拒绝
• 单张解压图片不得超过 1 GB，压缩包全量解压总量不得超过 3 GB

测试

当前测试覆盖：

• 文件夹图片自然排序
• ZIP/CBZ 安全路径和读取模式
• 大型压缩包按需读取
• 损坏缓存页自动修复
• ZIP 不支持压缩方式提示
• 缓存统计与清理
• 阅读进度计算
• 页码与滚动偏移双向映射、长图分块可见范围
• 明暗主题与最近阅读批量删除

运行：

flutter test --reporter expanded

隐私说明

看漫工具不包含账号系统、云同步、广告或漫画内容上传功能。漫画原文件、解压缓存、阅读进度和日志均保存在本机。