文件哈希批量计算 - 免费批量算哈希并导出一份能直接发给对方的校验清单（其它工具）

这个工具解决什么问题

给客户交付资料包或者发布一个安装包的时候，对方经常提一个要求：麻烦附一份校验值（MD5 或者 SHA256），好确认文件在传输过程里没有损坏、没有被中间环节改过。本来这事不难，麻烦在于数量 —— 一个压缩包三十几个文件，要一个个算。用系统自带的方式，点开一个算一个、算完手动把那一串十六进制值复制出来，再切回表格里粘进对应行；中间一旦切错窗口，粘错行的概率很高，几十行下来还得回头抽查一遍。更麻烦的是最后一步：要把这些值整理成一份能随包发出去的文件，手工排版又是一轮复制粘贴，一个下午就搭进去了。

• 原来的做法：一个文件一个文件地算：逐个点开、逐个复制粘贴到表格里，最后再手工排版成一份清单
• 用这个工具：把整个文件夹拖进窗口，一次算完所有文件，直接导出成可随包发出去的校验清单
• 省下来的：三四十个文件从「一整个下午」压到「十几秒」，且不会抄错行

技术实现

工具本身不复杂，难点全在「大文件不卡死」和「批量不出错」这两件事上。整体是 core 与 gui 两层：core（hash_core.py）是纯逻辑、不依赖界面，负责算哈希、展开文件清单、生成清单与表格；gui（hash_batch_gui.py）只负责把用户点出来的选择翻译成 core 的函数调用。这样拆的好处是核心逻辑可以在无窗口环境下被逐条断言，而界面层薄到几乎没有出错空间。计算全部跑在后台线程里，通过消息队列把进度搬回界面，所以点下按钮之后界面不会假死，进度条会持续走，随时能停。

• 大文件按块流式读取（内存占用与文件大小无关）：用 hashlib 算法对象的 update() 增量喂数据，每次只读一小块（默认 8 MB，可选 1–32 MB）。一次性 read() 整个文件的话，内存占用就等于文件大小，几百 MB 就卡顿、上 GB 直接吃爆内存。分块之后算 20 GB 的镜像也只占几 MB 内存。分块大小不影响结果 —— 哈希算法是流式的，输入相同、切分不同，结果必然一致（自测里用同一个文件分别按 1 MB 和 32 MB 分块验证过）。
• 一次读盘、多算法并行：同一块数据依次 update 给所有被勾选的算法对象，磁盘只读一遍。若按算法各读一遍文件，同时勾 MD5/SHA1/SHA256/SHA512 就要读 4 遍盘，大文件上耗时直接是 4 倍。这里的取舍是「多花一点 CPU、少读三次盘」——磁盘 I/O 通常才是瓶颈。
• 失败隔离：一个坏文件不让整批白跑：文件被占用、权限不足、路径过长都会抛 OSError，实现上把错误只写进那一行结果，其余文件照常计算。系统错误会被翻译成人话：读取 Errno 32 显示为「文件正被其它程序占用，请先关闭占用它的程序」、Errno 5 显示为「没有读取权限」，而不是把一串英文报错丢给用户。另外「用户点了停止」与「文件算失败」是两种状态，分开记录，统计里不混。
• 校验清单用通行的书写格式：清单正文每行是「哈希值 + 两个空格 + 文件名」，这是哈希清单的通行形状，对方拿到后可以逐行核对。头部用 # 注释写明工具名、生成时间、算法、文件数与合计大小。清单文件写成 UTF-8 且不带 BOM —— BOM 会粘在第一个字节上，让按行解析的工具对不上；而导出的 CSV 表格相反，用带 BOM 的 UTF-8，因为 Excel 靠 BOM 判断编码，没有它中文会乱码。
• 文件名相对化 + 输入去重：清单与表格里显示的是相对公共根目录的路径，不是绝对路径：交付给客户的表格里带本机用户名和目录结构既没用又泄露隐私，但只写文件名又会让多层目录下两个同名文件分不清。输入去重按规范化后的绝对路径比较，同一个文件拖两次只算一次，不会在结果表里出现两行一样的。
• 后台线程 + 消息队列，界面不假死：tkinter 不是线程安全的，从子线程直接操控件会随机崩溃。因此计算跑在用 threading 起的后台线程里，只往 queue 塞消息；主线程每 80 毫秒把消息搬进界面。停止用 Event 置位实现，读文件的循环在每个分块开始处检查一次，最长读完当前这一块就停（默认 8 MB，几乎即时），已算完的结果全部保留。

技术栈：Python 3.8+（纯标准库）、hashlib 增量哈希、tkinter 图形界面、threading 后台计算、PyInstaller 单文件打包

已知局限：只做读取与计算，不修改任何文件；耗时受磁盘速度限制，机械硬盘上 10 GB 的镜像大约 1–2 分钟（界面有进度条与停止按钮）；校验清单头部是注释行，若对方用的是只认纯哈希行的严格解析器，需要去掉 # 开头的行，正文本身是标准形状。

操作教程

1. 把要算的文件加进来
   点左上「添加文件…」可以在系统文件对话框里框选多个文件；点「添加文件夹…」选一个文件夹。选文件夹时勾上「包含子文件夹」，会把里面所有层级的文件一起算进来。
   预期结果：上方列表出现文件清单，每行显示序号、文件名、大小和所在位置，右上角显示「待计算 N 个文件 · 合计大小」。
2. 确认要算哪些算法
   「计算选项」里勾选 MD5 / SHA1 / SHA256 / SHA512，默认已勾 SHA256（交付校验最常用）。可以同时勾多个，同时勾多个不会多读几遍磁盘。需要大写格式就点上「大写」。
   预期结果：结果表格的列会跟着勾选变化：只勾 SHA256 就只出现 SHA256 一列，不会留一片空列。
3. 点「开始计算」
   点蓝色「开始计算」按钮。计算在后台跑，进度条实时推进，右边数字显示已完成文件数 / 总文件数。中途想停就点「停止」。
   预期结果：结果表格逐行填入文件名、大小、各算法哈希值与用时。行会随计算完成自动滚到最新一行。
4. 复制结果发给对方
   选中若干行点「复制选中行」，剪贴板里就是纯哈希值；点「复制整张表」会连文件名一起复制，粘进 Excel 会自动按列分开。
   预期结果：状态栏提示「已复制到剪贴板」，粘贴到聊天窗口或 Excel 即可看到内容。
5. 导出校验清单（交付场景最常用）
   先在最右侧「清单算法」下拉框里选一个算法（默认 SHA256），再点「导出校验清单…」，选保存位置。
   预期结果：生成一份文本清单：头部说明工具名、生成时间、算法、文件数与合计大小，正文每行一个文件。这份文件可以直接随包发给客户。
6. 导出结果表格（需要归档时用）
   点「导出 CSV 表格…」保存成 CSV。Excel 双击就能打开，中文不会乱码。
   预期结果：导出成功后会询问是否打开所在文件夹，点「是」直接在资源管理器里定位到刚导出的文件。

常见问题

技术实现与后续维护

本工具由我们自行开发并持续维护，每次迭代都先在本地把核心逻辑的回归测试跑绿再发布。实现上刻意把「算哈希」与「画界面」拆成两层：核心逻辑不依赖界面，因此能被自动化断言覆盖，也更便于日后按你的场景调整。下面说明它的技术构成与可扩展方向，方便你判断是否契合自己的流程。

技术构成：

• src/hash_core.py —— 核心逻辑：按块算哈希、展开文件清单、生成校验清单与 CSV。纯函数、不依赖界面，可被自测直接调用
• src/hash_batch_gui.py —— 图形界面（tkinter）：文件列表、算法选项、进度条、结果表格、复制与导出按钮
• src/selftest.py —— 核心逻辑回归自测，121 项断言，覆盖分块、多算法、失败隔离、清单格式、CSV 编码等
• build.bat —— 用 PyInstaller 打包成单文件 exe（带 --noconsole，双击不弹黑框）
• requirements.txt —— 依赖说明：运行时零第三方依赖，全部使用 Python 标准库

运行环境：

运行环境：Windows 10 / 11（64 位）。运行版是打包好的单文件程序，解压后双击即可，不需要安装 Python，也不需要配置任何运行环境，全程鼠标操作。技术依赖：本工具只使用 Python 标准库 —— hashlib 负责哈希计算，tkinter 负责窗口界面，没有任何第三方库，所以在任何 Windows 10/11 机器上都能直接运行。界面层与核心逻辑分属两个模块，核心逻辑可独立测试，便于后续维护与扩展。

可扩展方向：

• 增加算法：hashlib 已内置 SHA3、BLAKE2 等，往算法清单里加一个名字，界面、表格、清单三处会自动跟着出现新列
• 核对手上的清单：清单解析函数已经能把清单读回成结构化数据，接一个「选文件 + 选清单 → 逐行比对 → 报出不一致条目」的界面即可
• 按哈希值找重复文件：对结果按哈希值分组就能实现，计算部分不用改
• 生成带目录树的清单：在清单头部注释区拼上目录结构，不影响正文的通行格式
• 多进程加速：可考虑按物理磁盘分组，同盘串行、异盘并行（单纯开多进程在固态硬盘上会互相抢带宽，收益不稳定）

本工具免费提供使用，但不对外分发源码。如果你需要在本工具基础上做功能调整、对接内部系统或长期维护，可以联系我们做二次开发，源码与工程文档可在定制合作中一并交付。

使用说明与免责声明

• 本工具在本地运行，不联网、不上传任何数据到服务器。
• 涉及文件改写的功能，请在使用前备份原始文件。
• 软件完全免费，可自由使用与转发，请勿用于倒卖。
• 因误操作造成的数据问题请自行承担。