写一个macOS重复文件清理工具：为什么哈希不是难点，误删防御才是核心

在开始开发 Find Duplicate Files 之前，我和很多开发者的想法一样：重复文件清理工具的逻辑应该非常简单——递归遍历指定文件夹，给每个文件算一遍哈希值，把哈希相同的文件聚类展示，再由用户勾选删除。

但当真正把这个工具推向真实用户的生产环境、面对数十万文件和数 TB 级的个人资料库时，我才深刻意识到：在大规模文件系统中，计算哈希从来不是核心技术壁垒；如何避免系统陷阱、如何在极端场景下构建坚不可摧的“误删防御架构”，才是此类工具的真正灵魂。

在之前的一篇记录中，我谈过产品层面的克制。本文从具体的工程实现、文件系统底层机制与架构设计，展开聊聊开发这款工具时的技术思考。

一、为什么不能盲目算全量哈希？——四级快速过滤管道

如果你对一个 2TB 的外置硬盘里所有文件直接执行全量 SHA-256 计算，机械硬盘的磁头会疯狂寻道，即便是高端 NVMe 固态硬盘也会面临巨大的 I/O 吞吐与 CPU 发热。

为了在数秒到数十秒内完成海量文件的比对，Find Duplicate Files 采用了分级的四级过滤管道（Multi-Stage Pipeline）：

[ 扫描目标目录 ]
       │
       ▼
[ Level 0: 过滤系统特殊节点 ]
       │
       ▼
[ Level 1: 按精确字节大小分组 (Size Bucket) ] ── (单文件直接排除)
       │
       ▼ (仅对存在2个及以上同大小文件的桶)
[ Level 2: 读取头尾 4KB 进行快速哈希 ] ── (哈希不同立即排除)
       │
       ▼ (仅对头尾哈希仍然一致的候选集)
[ Level 3: 全量 SHA-256 分块流计算 ] ──> [ 确认完全重复 ]

通过这套管道，一个包含 100,000 个文件的目录，真正需要走完 Level 3 全量哈希计算的文件往往不足 5%，整个扫描过程的 I/O 开销被压缩到极致。

二、macOS 文件系统（APFS）的隐形陷阱

在 macOS 平台上做底层文件操作，如果不理解苹果 APFS（Apple File System）的特性，很容易造成灾难性后果：

1. 硬链接（Hard Links）不是重复文件

如果两个文件路径指向同一个磁盘物理 inode（即硬链接），它们共享同一块磁盘空间。

• 如果软件把它们当成“重复文件”并删除了其中一个，不仅无法释放哪怕 1 字节的空间，还会破坏依赖硬链接的备份系统（如 Time Machine 本地快照）或开发环境。
• 解决方案：在元数据收集阶段，记录每个文件的 stat.st_ino 与 stat.st_dev。属于相同设备且相同 inode 的条目自动归并为引用镜像，严禁作为重复项提供删除。

2. APFS 克隆文件（Copy-on-Write）的容量误区

在 APFS 文件系统中，用户在访达（Finder）里“复制”一个 10GB 的文件，耗时通常不到 0.1 秒。这是因为 APFS 采用了写时复制（Clone Extents）技术，两个文件在修改前共享底层存储块。

• 这类文件在哈希层面确实完全一致，但删除其中一个并不能为用户立刻腾出 10GB 的物理可用空间。
• 解决方案：工具在报告中必须清晰区分“文件逻辑大小”与“预估释放物理空间”，避免给用户造成空间释放虚标的困惑。

3. 包内容（Bundle）与只读图库保护

macOS 系统中大量看似普通的文件实际上是目录包（如 .app、.photoslibrary、.keynote）。

• 如果递归进入这类包内部，把里面的公用图标、配置文件当成重复文件删掉，整个应用程序或照片图库就会直接损坏。
• 解决方案：对 Package Bundle 设置默认穿透黑名单，并对系统的受保护目录设置严格的安全隔离屏障。

三、误删防御机制的工程设计

在文件管理工具中，“快速”只是及格线，“安全”才是生死线。为了将误删风险降至零，我在软件中设计了以下四重防护墙：

1. 扫描与清理完全解耦，严禁隐式自动操作

软件的扫描引擎是**纯只读（Read-Only）**的。无论扫描出多少 GB 的重复文件，绝不提供任何未经确认的“一键后台自动清空”按钮。所有的扫描结果必须以可展开、可追溯的路径列表清晰呈现在用户面前。

2. 执行删除前“纳秒级”重新校验

用户扫描完文件后，可能几个小时甚至几天后才回来执行清理。在这期间，文件可能已经被重命名、被外部程序修改或者被覆盖。

因此在用户点击“确认清理”的一瞬间，软件会启动二次即时重验机制：

• 重新读取目标文件的最后修改时间（mtime）和文件大小；
• 重新计算并比对 SHA-256 签名；
• 若发现文件在扫描后发生过任何变动，立即中止清理操作并弹出警示，要求重新扫描。

3. 永远优先使用系统废纸篓与隔离目录

在本地工具中，严禁直接调用不可逆的物理擦除指令：

• 默认策略：通过 macOS 系统的 NSWorkspace.shared.recycle 将文件移至系统废纸篓。用户如果后悔，随时可以在访达中“放回原处”。
• 隔离归档模式（Quarantine Sandbox）：对于包含大量关联配置的文件，支持一键将重复项整体移动到一个独立的本地区离目录中。用户可以正常运行几天项目，确认一切正常后再彻底清空。

4. 扫描快照的加密签名防篡改

软件支持将大型扫描结果导出或保存为历史快照。为了防止快照文件因磁盘损坏或人为篡改而导致读取到错误路径：

• 每一个快照文件在生成时均附加 HMAC / SHA-256 完整性签名；
• 重新打开历史快照时先验签，若验签失败或来自未签名格式，仅允许只读查看统计，彻底禁用选择和清理功能。

四、写给独立开发者的总结

做一个实用的本地工具，最难的往往不是编写核心算法，而是抑制开发者自己的“过度自动化”冲动。

• 激进的工具追求的是“帮用户做决定，点击一次搞定一切”；
• 而本地优先的工具追求的是“把客观事实精准呈现出来，把最后的决定权和知情权稳稳交还给用户”。

宁可让流程多一次弹窗确认，宁可让校验多消耗几百毫秒，也绝不让任何一份唯一的珍贵数据面临丢失的风险。这是我在做 Find Duplicate Files 时始终坚守的底线。