TreeMap 重复文件检测内置两套互补引擎：分阶段 SHA-256 内容哈希精准找出逐字节相同的"真重复"，64 位感知哈希 dHash 则能抓住被缩放、重新编码过的相似图片。本文带你完整看懂它如何分三阶段省掉 99% 的无谓读取、如何避免误删，以及相似图片的阈值该怎么调。

一分钟上手：找到重复文件的 3 个步骤

TreeMap 是一款可在 Mac、Windows、Linux 上运行的磁盘可视化工具，扫描完成后即可开始"重复文件狩猎"：

1. 完成一次扫描—— 重复检测建立在扫描结果树上，扫描未完成时接口会返回 409（SCAN_RUNNING）提示稍后再试；
2. 打开 Duplicates 视图—— 默认只统计 ≥ 1 KB（十进制 1,000 字节）的文件，小文件噪音被过滤，可传minSize参数调整；
3. 等待后台哈希任务—— 任务按扫描 ID 建立，前端轮询进度；运行中返回 202 + 进度，完成后返回 200 + 重复分组，每组的"可回收空间"会逐组列出。

任务进度会明确告诉你当前处于哪个阶段（sizes→partial→full），这正是下面三阶段哈希的直观体现。

核心机制：SHA-256 分阶段哈希为什么快

朴素做法是对每个文件都算完整 SHA-256，磁盘读满一遍。TreeMap 的做法是"由便宜到昂贵"三级过滤，源码位于 duplicateFinder.ts：

第 1 阶段：按精确大小分桶（零成本）

大小完全来自扫描树，不读任何文件内容——大小不同的文件绝不可能是内容重复，一步筛掉绝大多数候选。只有同桶且 ≥ 2 个文件才进入下一阶段。

第 2 阶段：只读前 64 KiB 做局部哈希

对每个候选文件仅读取开头 64 KiB 计算 SHA-256。绝大多数"同大小"文件在这里就会分道扬镳，绝大多数磁盘 I/O 被省掉。

第 3 阶段：完整流式 SHA-256

只对"前 64 KiB 都相同"的幸存文件，用流式读取算完整 SHA-256（见 hashFile），全程以 4 路并发（HASH_CONCURRENCY = 4）后台运行，不阻塞界面。

这种分层设计让全盘扫描后找重复的代价，从"再读一遍整个磁盘"降到"几乎只读同大小文件的头部"。

它如何避免"越帮越忙"：边界情况一览

重复检测最怕误报，TreeMap 对这些棘手场景都做了诚实处理：

• ☁️云端占位文件（iCloud / OneDrive / Dropbox）永不打开—— 读取占位符会触发下载，所以它们只被计入notHashed统计（多少个、多大），绝不参与比较，界面也会如实说明；
• 🔗符号链接不读—— 跟随链接读到的可能是另一个文件，甚至一个 Windows 云端重解析点；
• 🪢硬链接—— 扫描器只在首个名字上计字节，其余名字大小为 0，天然不会进桶被误判；
• 📦macOS APFS 克隆—— Finder 的"制作副本"与原件共享底层数据块，删掉副本并不省空间，因此界面会把可回收数字标注为"上界"并给出说明；
• ⏳扫描后数据已同步走—— 读取前会再次确认文件仍在本地，确认不了的宁可跳过并计入缺口，绝不假装"没发现重复"。

感知哈希 dHash：相似图片也能被抓住

字节级哈希有个盲区：同一张照片的截图版、缩小版、重编码版，一个字节不同就逃过 SHA-256。TreeMap 的 Near-duplicate images 标签页用 64 位dHash补上这块，实现在 perceptualDupes.ts：

1. 解码—— 图片被解码并缩放为 9×8 的灰度图（8 行 9 列）；
2. 取指纹—— 每行比较相邻像素的明暗关系，得到 8 位，共 8 行 = 64 位 dHash；
3. 比距离—— 两张图的 dHash 用汉明距离衡量差异，小于等于阈值即判为"相似"。

关键参数速查：

• threshold 阈值：默认10（0–32）。值越小越严格，误报越少；值越大越宽松，可能把不同图片聚到一起；
• 支持格式：jpg / jpeg / png / gif / webp / bmp / tiff / heic / heif / avif；
• 大小门槛：小于 4 KB 的图（favicon 级）直接跳过，避免淹没真照片；
• 数量上限：最多比较 8,000 张（按大小取最大的），防止 O(n²) 聚类的计算爆炸，超限会如实标记truncated；
• 解码器：优先用 sharp（4 路并发），无 sharp 时回退 ffmpeg，两者都没有则明确报告"不可用"而不是静默失败。

相似图片会经并查集聚类成"簇"，每簇内按修改时间从新到旧排列——自动选择会保留最新的一份。点击 Compare 可以并排查看缩略图、尺寸、EXIF 拍摄日期，还能看到两图"64 个块中相差 4 块"的 dHash 差异高亮，删不删心里有数。

读懂结果：可回收空间是怎么算的

每个重复组的可回收空间 = 文件大小 × (数量 − 1)，即保留一份后省下的部分；簇内按可回收量从高到低排序，先看"最值得动手"的组。注意 macOS 上的 APFS 克隆说明（见上文），那是一组"理论上限"。

相关接口与源码地图

MCP 用户还可直接调用find_duplicates工具获取真重复结果。想亲自上手的话：

git clone https://gitcode.com/gh_mirrors/tr/TreeMap-Disk-Visualizer cd TreeMap-Disk-Visualizer npm install && npm start

常见问题 FAQ

问：重复检测会把文件删错吗？不会自动删。每组都有 Compare 视图展示缩略图、路径、拍摄日期与推荐保留项，删除规则还会被明文写出；批量清理最终都进入 Clean Up 购物车人工确认。

问：为什么云端文件不在结果里？打开 iCloud/OneDrive 占位文件等于下载它。TreeMap 选择跳过并如实报告"多少张图未比较、占多少字节"，宁可答案有缺口也不悄悄下载。

问：图片太多检测会卡吗？会按大小取最大的 8,000 张比较，任务全程显示hashed / toHash进度，且可随时取消（cancelAllNearDupeJobs语义下的取消标记会让聚类循环提前退出）。

问：阈值 10 该怎么调？照片缩略图、截图副本一般 5–10 就能聚到一起；如果不同照片也被误判为一组，把 threshold 调小即可。