WxCleaner核心源码解读：scanner.py如何用不到百行Python实现极速重复文件扫描器

WxCleaner 是一款微信重复文件清理工具，它的核心引擎 scanner.py 仅用 120 多行 Python 代码，就实现了一个极速、准确的重复文件扫描器。本文带你逐段读懂这套"三级筛选"架构：为什么扫几万张照片也不卡，为什么哈希计算量比朴素方案少几个数量级，以及进度条是如何与 GUI 协作的。

为什么朴素方案很慢？

最直觉的做法是：对每个文件算一遍完整 SHA-256，再两两比对。但微信文件夹动辄几十万文件，全量哈希每个文件意味着海量磁盘 IO——这才是重复文件扫描慢的根源。

WxCleaner 的思路很经典：用便宜的判断先淘汰大多数文件，把昂贵的哈希留给极少数"嫌疑人"。整条流水线只有三级：

下面逐段看代码如何实现。

核心函数 calculate_hash：分块读取 + 双模式

哈希计算的入口是 calculate_hash，它同时支持"快筛模式"和"精确模式"：

def calculate_hash(file_path, block_size=65536, partial=False): hasher = hashlib.sha256() with open(file_path, 'rb') as f: if partial: buf = f.read(1024) # 快筛：只读前 1024 字节 hasher.update(buf) else: buf = f.read(block_size) # 精确：分块读，每次 64KB while len(buf) > 0: hasher.update(buf) buf = f.read(block_size) return hasher.hexdigest()

三个值得学习的设计细节：

• partial=True只读前 1024 字节。绝大多数不重复的文件在这一步就被淘汰，一个 4GB 的视频只需读 1KB 就能排除，这是"极速"的关键。
• 分块读取（64KB）而非一次f.read()。即使处理超大文件，内存占用也始终恒定在几十 KB，不会因为单个大文件把内存吃光。
• 异常时返回None而不是抛出。文件被占用、权限不足、软链接断裂等情况都会被静默跳过，扫描不会中途崩溃——这对"扫全盘"类工具至关重要。

扫描主流程 find_duplicates：一条四级流水线

find_duplicates 是整条流水线的调度中心，四个步骤依次递进：

第 0 步：预扫描统计文件总数

total_files = 0 for root, _, files in os.walk(scan_path): total_files += len(files)

先完整走一遍目录树（见 scanner.py#L32-L41），只为拿到文件总数。这个数字后面用来驱动进度条——没有它，进度就只能瞎跳。

第 1 步：按大小分组（最便宜的淘汰器）

size_groups = defaultdict(list) for root, _, files in os.walk(scan_path): for name in files: size = os.path.getsize(path) if size > 0: # 忽略空文件 size_groups[size].append(path)

defaultdict以文件大小为键，把同尺寸的文件归到一组。getsize只读文件系统元数据，不触碰文件内容，速度极快。此时只剩"同尺寸组"才值得进入下一关（见 scanner.py#L43-L59）。

第 2 步：头部哈希（Partial Hash）

对每个len(paths) > 1的同尺寸组，调用calculate_hash(path, partial=True)，以(size, 头部哈希)为键二次分组（见 scanner.py#L73-L86）。这一步淘汰掉"尺寸碰巧相同但内容开头不同"的绝大多数文件。

第 3 步：全量哈希（终极裁决）

只有头部哈希也相同的文件，才会被完整读取并计算全量 SHA-256（见 scanner.py#L88-L105）。最终过滤掉孤例，返回字典：

return {h: paths for h, paths in duplicates.items() if len(paths) > 1}

结构是{哈希值: [文件1, 文件2, ...]}——一个哈希对应一组完全重复的文件，直接交给界面展示。

💡复杂度直觉：假设目录有 10 万个文件，同尺寸的约 5%，同尺寸的里再同头部哈希的约 1%。那么"昂贵"的全量哈希只发生在约 50 个文件上，而不是 10 万个——筛选漏斗把 IO 成本砍掉了两个数量级。

进度回调：让扫描器"懂 UI"

find_duplicates接受一个可选参数progress_callback(current, total, status_text)。注意源码里一个精巧的进度映射策略：

# 第一阶段(Walk)完成后，进度设为 50% # 第二阶段(Hash)处理剩下的 50% p = 0.5 * total_files + 0.25 * total_files * (current_hash_processed / potential_duplicates_count)

源码把整个进度条切成三段区间（0–50% 大小筛选、50–75% 头部哈希、75–100% 全量校验，见 scanner.py#L62-L105），并且每处理 100 个文件才回调一次，避免高频刷新拖慢扫描本身。

GUI 侧如何安全地接收回调？

扫描在独立线程中运行（wx_gui.py 的run_scan），但 Tkinter 不是线程安全的。WxCleaner 的解法只有一行核心代码：

def progress_callback(current, total, status_text): def _update(): self.status_label.config(text=status_text) self.progress['value'] = pct self.root.after(0, _update) # 把 UI 更新"投递"回主线程

root.after(0, ...)是标准的 tkinter 线程跳转技巧：工作线程不直接碰控件，而是把更新请求排进主线程事件队列。入口在 start_scan_thread：

threading.Thread(target=self.run_scan, args=(path,), daemon=True).start()

这个"扫描与界面解耦"的架构，正是程序扫几十万文件也不卡顿的原因。

不用装 GUI 也能自测：__main__彩蛋

scanner.py 末尾 还藏了一段自测逻辑：直接运行该文件，它会自己创建一个test_folder，写入两个相同文件和一个不同文件，然后验证能否正确找出一组重复：

python scanner.py

输出类似：

找到 1 组重复文件: Hash 315f5bdb: ['file1.txt', 'file2.txt']

这个设计让核心算法可以脱离界面独立测试，对阅读和调试源码非常友好。

项目结构一览

WxCleaner/ ├── main.py # 程序入口，启动 ttkbootstrap 窗口 ├── scanner.py # 核心：三级筛选重复文件扫描器（本文主角） ├── wx_gui.py # GUI：扫描线程、结果列表、标记与删除 ├── WxCleaner_bundled.py # PyInstaller 打包用的单文件版本 ├── requirements.txt # 依赖：ttkbootstrap、send2trash └── LICENSE # MIT 许可证

扫描器找到重复后，wx_gui.py 的 delete_selected 会经二次确认，把文件移至回收站（依赖 requirements.txt 中的send2trash）而非直接删除，配合"默认保留路径最短文件"的自动标记策略，构成完整的"扫描 → 预览 → 安全清理"闭环。

总结：三个可以带走的设计模式

1. 漏斗式筛选：用"元数据 → 局部内容 → 全量内容"成本递增的判断淘汰文件，昂贵操作只留给极少数，这是所有高性能重复文件扫描器的通用范式。
2. 分块读文件：恒定内存占用处理任意大小的文件，是 Python 文件 IO 的最佳实践。
3. 回调 + 事件队列：通过progress_callback参数解耦算法与界面，算法不知道自己在被 GUI 调用，也能被命令行、测试代码直接复用。

不到百行核心代码，却麻雀虽小、五脏俱全。如果你想动手改造（比如把 SHA-256 换成更快的 BLAKE3、或用concurrent.futures并行哈希），scanner.py 会是绝佳的练手起点。