Czkawka 磁盘清理工具完整指南Rust 如何实现高速重复文件与相似图像查找【免费下载链接】czkawkaMulti functional app to find duplicates, empty folders, similar images etc.项目地址: https://gitcode.com/GitHub_Trending/cz/czkawkaCzkawka波兰语打嗝之意是一款用 Rust 编写的开源磁盘清理工具其新一代图形界面 Krokiet 基于 Slint 框架构建。它通过 14 个扫描模块解决重复文件、相似图片、损坏文件等问题完全离线运行覆盖 Linux、Windows、macOS、FreeBSD 和 Android。下面从架构、核心机制到调优与排障完整拆解这套磁盘清理工具的实现思路与用法。一、项目快照一个核心库加四个前端整个项目是一个 Cargo 工作区workspace五个成员共享同一个扫描引擎czkawka/ ├── czkawka_core/ # 核心扫描引擎无任何 UI 依赖 │ ├── benches/ # Criterion 基准测试哈希、相似图像 │ └── src/ │ ├── common/ # 目录遍历、缓存、进度、线程、扩展名过滤 │ ├── helpers/ # FFmpeg/ffprobe 调用、延迟发送器 │ └── tools/ # 14 个独立工具模块 ├── czkawka_cli/ # 命令行前端面向自动化脚本 ├── czkawka_gui/ # GTK4 前端12.0 后停止发布新二进制 ├── krokiet/ # 主力桌面 GUISlint 框架 └── cedinia/ # Android 触控版Slint 框架技术栈要点语言Rust官方说明接近 100% 无 unsafe 代码GUI 框架SlintKrokiet 与 Cedinia和 GTK4旧版 Czkawka GUI工具矩阵重复文件、空文件夹、大文件、空文件、临时文件、相似图像、相似视频、相同音乐标签/内容、无效符号链接、损坏文件、错误扩展名、EXIF 清除器、视频优化器、不良文件名共 14 项许可CLI 与 GTK 版为 MITKrokiet 与 Cedinia 因 Slint 的许可要求为 GPL-3.0-only。相比之下同类工具多为单前端结构而这里引擎与界面彻底分离意味着任何新前端包括第三方 Tauri 应用只需依赖czkawka_core一个 crate 即可复用全部扫描能力。二、它为何存在内存安全 零网络依赖的路线选择现有方案各有短板。Python 系的 FSlint、DupeGuru、Bleachbit 功能齐全但依赖 Python 解释器运行时内存占用偏高且部分工具多年未更新C/C 写的 rdfind、fclones 速度快但内存安全靠程序员自觉商业清理软件则普遍需要联网。项目 README 中的对比表可以直观看到各家的覆盖差异能力KrokietCzkawka(GTK)CediniaFSlintDupeGuruBleachbit重复文件查找✅✅✅✅✅❌相似图像✅✅✅❌✅❌相似视频音频画面✅✅仅音频❌❌❌相同音乐标签/内容✅✅仅标签❌仅标签❌无效符号链接✅✅❌✅❌❌损坏文件检测✅✅✅❌❌❌EXIF 清理 / 视频优化✅❌仅 EXIF❌❌❌缓存支持✅✅✅❌✅❌运行语言RustRustRustPythonPython/Obj-CPython支持系统Lin/Mac/WinLin/Mac/WinAndroidLinLin/Mac/WinLin/Mac/Win持续开发中✅停更✅❌基本停更✅Czkawka 的技术路线是三点组合其一用 Rust 的所有权系统替代手动管理 垃圾回收在保持接近 C 级性能的同时消除数据竞争其二所有扫描结果持久化到本地缓存让第二次扫描显著快于第一次其三程序不具备任何网络能力——不采集统计、不检查更新——离线运行本身就是一种隐私承诺。三、核心机制拆解渐进式比对、预哈希缓存、并行遍历1. 三级渐进式比对用便宜的键先筛一遍重复文件查找的主实现位于 czkawka_core/src/tools/duplicate/。核心思想是不同文件的名字、大小绝大多数时候就不同而计算哈希最贵所以先用免费的信息分组只对剩下的候选计算哈希。// 第一级按文件名可配置大小写敏感分组 pub(crate) fn check_files_name(mut self, stop_flag: ArcAtomicBool, progress_sender: OptionSenderProgressData) - WorkContinueStatus { let group_by_func if self.get_params().case_sensitive_name_comparison { |fe: FileEntry| fe.path.file_name()...to_string() } else { |fe: FileEntry| fe.path.file_name()...to_lowercase() }; let result DirTraversalBuilder::new() .common_data(self.common_data) .group_by(group_by_func) .checking_method(CheckingMethod::Name) .stop_flag(stop_flag) .build() .run(); // 只保留组内文件数 1 的分组单文件直接丢弃 }分组函数以闭包形式注入目录遍历器同一套遍历逻辑按名字 → 大小 → 大小名字 → 哈希逐级收窄。收益很直接只有名字相同或大小相同的文件才会进入下一级哈希计算量因此远小于全量计算哈希再比对。哈希算法支持 Blake3、CRC32、XXH3 三种通过HashType统一封装见 tools/duplicate/mod.rs。2. 预哈希prehash缓存只读文件头尾 4KB完整哈希在第二遍扫描里往往是大开销。Czkawka 的对策是 prehash先只哈希文件的开头 4KB 和结尾 4KBPREHASHING_BUFFER_SIZE 4 * 1024把这个廉价摘要连同文件大小、修改时间一起写入缓存。再次扫描时若文件的这两个值都没变就认为内容未变直接跳过完整哈希。pub fn hash_calculation_limit(buffer: mut [u8], file_entry: DuplicateEntry, hash_type: HashType, limit: u64, size_counter: ArcAtomicU64) - ResultString, String { // size 2*limit 时整个文件一次读入 // 否则读前 limit 字节 seek 到尾部读后 limit 字节 if file_entry.size 2 * limit { let n read_filling(mut file_handler, mut buffer[..file_entry.size as usize])?; hasher.update(buffer[..n]); } else { // 头部与尾部各读一段喂给同一个 hasher } Ok(hasher.finalize()) }12.0 版本还特意把尾部也纳入 prehash原因是很多看似相同的文件差异恰好在文件末尾。值得注意的是read_filling会循环调用read直到缓冲区填满——因为标准库允许短读单次调用可能少读字节导致两次运行产生不同摘要该缺陷在 12.0 中修复。Krokiet 默认启用预哈希缓存CLI 需显式加--use-prehash-cache。3. 缓存体系带版本号、双格式、每周自动清理缓存实现集中在 czkawka_core/src/common/cache.rspub(crate) const CACHE_VERSION: u8 100; pub(crate) const CACHE_DUPLICATE_VERSION: u8 120; const MEMORY_LIMIT: u64 8 * 1024 * 1024 * 1024; // 反序列化上限 8GB static CACHE_CLEANING_INTERVAL_SECONDS: Lazyu64 Lazy::new(|| { option_env!(CZKAWKA_CACHE_CLEANING_INTERVAL_SECONDS) .and_then(|s| s.parse::u64().ok()) .unwrap_or(7 * 24 * 60 * 60) // 默认 7 天清理一次过期条目 });每个工具族有独立版本号重复文件、图像、视频、损坏文件各一套算法变更时旧缓存自动失效重建不需要用户手动处理。所有前端共享同一目录如 Linux 的~/.cache/czkawka/并支持.bin.json双格式落盘——JSON 版方便人工编辑比如把文件库挪到另一块磁盘时。缓存校验时会比对大小与修改时间不一致的条目按未缓存处理。4. 并行目录遍历Builder Rayon所有工具的文件收集都走 common/dir_traversal.rs 中的DirTraversalBuilder。Builder 收集根目录、扩展名过滤、排除的 glob 模式、文件大小上下限、停止标志ArcAtomicBool和进度发送端crossbeam channelrun()内部用 Rayon 线程池并行枚举文件系统并做边遍历边分组进度数据通过 channel 推给 GUI 线程。停止扫描是协作式的哈希循环在每次read后检查stop_flag且中断前已计算的哈希均已进入缓存因此部分扫描不会浪费。四、它有多快基准测试与调优参数项目自带 Criterion 基准测试 benches/hash_calculation_benchmark.rs覆盖16MB 文件 × 16KB/1MB 缓冲区 × Vec/数组缓冲区四种组合衡量hash_calculation在 Blake3 下的吞吐。具体数字依赖本机硬件运行cargo bench -p czkawka_core可在自己机器上复现不建议直接引用跨机器的标准值。影响速度的关键设计如下机制实现位置效果三级比对名字/大小/哈希tools/duplicate/core.rs哈希只算给通过前两级筛选的候选文件Prehash 头尾 4KB 缓存tools/duplicate/mod.rs二次扫描中未变化文件免全量哈希线程本地 2MB 缓冲区THREAD_BUFFER_SIZE同上每个工作线程复用缓冲避免反复分配Rayon 并行遍历 流式分组common/dir_traversal.rsIO 与分组重叠执行吞吐随核心数扩展缓存反序列化 8GB 上限common/cache.rs防超大缓存文件打爆内存图像加载 500MB 大小护栏12.0.1Changelog防止异常大图解码导致 OOM可执行的调优参数按收益排序哈希算法默认 Blake3 吞吐最高极端 HDD 场景可换 CRC32 降低 CPU 占比-s crc32预哈希缓存Krokiet 默认开启CLI 加--use-prehash-cache。若在意缓存体积可关闭文件大小边界设minimal_file_size跳过零碎小文件设上限避免个别超大文件拖慢进度编译期优化RUSTFLAGS-C target-cpunative cargo build --release可使 x86_64 图像哈希提速约 10–20%项目 Instruction.md 给出的参考值release 配置加lto thin还能显著缩小二进制线程数Rayon 默认按逻辑核心数建池可用环境变量RAYON_NUM_THREADS手动限制适合在笔记本上避免风扇狂转便携化CZKAWKA_CONFIG_PATH与CZKAWKA_CACHE_PATH环境变量可把配置和缓存指向 U 盘目录配合缓存可让同一台扫描库随身携带。五、实战指南三个典型场景与排障清单场景 1家庭目录重复文件排查CLIczkawka_cli dup -d /home/you \ -e /home/you/Downloads \ -x jpg png mp4 \ -s hash \ -f results.txt-d指定扫描目录-e排除目录-x限定扩展名-s hash表示按哈希精确比对-f输出结果文件。多数工具还支持dry_run与move_to_trash选项11.0 起加入建议首次运行先 dry-run 看结果再决定清理。场景 2照片库相似图像去重相似图像工具基于感知哈希参数max_difference取值 0–40数值越大越宽松11.0 起由旧版相似度假设改为该整数差值。照片库建议从默认值起步命中过多再调小。12.0 新增了几何不变性支持镜像、翻转、旋转后的图片也能被匹配。若图片库很大且缓存加载变慢可先删除对应cache_similar_image_*.bin文件下次扫描会只针对当前条目重建Instruction.md 官方建议。场景 3U 盘便携版 外置硬盘扫描外置硬盘要特别注意缓存策略项目文档明确建议对经常插拔的移动磁盘关闭自动删除过期缓存条目改用手动清理否则拔线期间的缓存会被判为过期而驱逐。便携脚本参考放 U 盘根目录#!/bin/bash CZKAWKA_CONFIG_PATH$(dirname $(realpath $0))/config \ CZKAWKA_CACHE_PATH$(dirname $(realpath $0))/cache \ ./krokiet常见问题排查顺序相似视频/视频优化无效果确认系统安装了 ffmpeg 与 ffprobe它们是这两个工具的运行时外部依赖缺失时相关功能不可用缓存加载慢或首次扫描异常定位到具体缓存文件cache_duplicates_HASH.txt、cache_similar_videos.bin等并重命名缓存会在下次扫描时重建12.0 升级后缓存失效属正常现象——损坏文件检测、相似图像几何不变性、相似视频新视觉匹配引擎的缓存格式变更官方会自动重建无需干预Windows 下 HEIF/RAW 支持不全预编译二进制未含 heif/libraw需自行编译并启用对应 feature扫描中途停止后白跑了没有——所有已计算的哈希在停止前已写入缓存下一次全量扫描会自动复用调试信息用RUST_LOGdebug提高日志级别Krokiet 12.0.1 还新增了关于/诊断面板可检查 HEIF/LibRAW/AVIF/FFmpeg 的编译与运行时可用性并实测指定图片能否解码。六、生态与走向作为库被复用的扫描引擎czkawka_core以标准 crate 形式发布是二次开发的主入口。目前的外部使用者包括一个 Tauri 编写的第三方 GUI 前端、一个文档去畸变库page-dewarp以及 CLI 的 JSON 结果封装工具官方同时提供 Python 绑定PyPI 上的czkawka包让 Python 脚本可直接调用扫描 API。若要扩展自定义工具可参照现有工具目录的组织方式每个工具一个子目录core.rs主逻辑 traits.rs参数/结果类型 tests.rs实现CommonData相关 trait 后即可复用目录遍历、缓存与进度框架入口见 czkawka_core/src/tools/。贡献路径在 README 中定义得相当具体报 issuebug 与异常行为、提 PR新功能建议先沟通复杂功能最好先有 Rust 实现的 POC 验证可行性、更新 Crowdin 上的翻译、制作各发行版/包管理器deb、rpm、Chocolatey、Homebrew、Winget的打包。仓库根目录的AGENTS.md与CLAUDE.md为 AI 辅助开发提供了风格约束维护者明确要求 AI 生成的 PR 也必须通过人工审查。从 Changelog 看近期节奏集中在相似视频引擎切换到similario_core新增窗口数、时长容差、子片段检测AV1 编码从 libaom 换成更快的 svtav1视频优化器加入降噪与自定义命令以及 Krokiet 的右键菜单、批量重命名、自定义选择弹窗等交互补全。GTK 版 12.0 已宣告停更Krokiet 与 Android 版 Cedinia 是当前开发主线。一句话收束Czkawka 用一个纯 Rust 核心库 多个薄前端的架构把磁盘清理做成了可嵌入、可离线、可缓存的工程项目——对你而言它既是今天就能跑起来的清理工具也是一个可以直接依赖的扫描库。【免费下载链接】czkawkaMulti functional app to find duplicates, empty folders, similar images etc.项目地址: https://gitcode.com/GitHub_Trending/cz/czkawka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考