Python 实战:用 wxPython 写一个 MD5 文件查重清理工具 摘要电脑用久之后经常会出现大量重复文件下载过多次的安装包、重复导出的照片、备份目录里的 Office 文档、压缩包副本等。手动查找既费时间也容易误删。本文记录一个完整的 Python 桌面工具项目使用wxPython编写界面使用MD5判断文件内容是否重复使用SQLite保存扫描记录使用JSON保存用户配置并在删除时将文件放入 Windows 回收站而不是直接永久删除。项目目标不是做一个复杂的商业软件而是做一个可运行、可维护、操作安全的本地小工具。C:\Users\86182\Desktop\文件查重功能效果这个工具支持以下功能选择一个文件夹进行查重。支持递归扫描子文件夹。使用 MD5 判断文件内容是否完全相同。重复文件按文件大小从大到小显示。每组重复文件默认保留修改时间最新的文件。支持批量勾选需要删除的重复文件。实时显示已选文件数量和预计释放空间。删除前弹窗确认。删除时放入回收站不直接永久删除。支持图片预览、ZIP 文件列表预览。PDF、Word、Excel、视频等文件显示基本信息并可调用系统默认程序打开。使用 SQLite 保存扫描结果。使用配置文件保存上次选择的目录和窗口设置。项目结构项目拆成多个小模块每个文件只负责一类事情文件查重/ ├── app.py # wxPython 主界面 ├── config.py # JSON 配置读写 ├── database.py # SQLite 数据库操作 ├── duplicate_finder.py # MD5 扫描和重复文件分组 ├── models.py # 数据模型 ├── preview.py # 文件预览信息 ├── recycle.py # 回收站删除 ├── start.bat # Windows 启动脚本 ├── README.md # 项目说明 └── tests/ # 单元测试这样拆分的好处是MD5 扫描、数据库、配置、删除逻辑都可以独立测试不会全部堆在 GUI 代码里。一、数据模型设计文件信息使用FileRecord表示重复文件组使用DuplicateGroup表示dataclass(frozenTrue)classFileRecord:path:strmd5:strsize:intmodified_at:floatdataclass(frozenTrue)classDuplicateGroup:md5:strsize:intfiles:tuple[FileRecord,...]propertydefkeep_file(self)-FileRecord:returnself.files[0]propertydefdelete_candidates(self)-tuple[FileRecord,...]:returnself.files[1:]这里约定每组重复文件内部files[0]是要保留的文件。程序默认按修改时间倒序排序所以最新文件排在第一位其余文件作为可删除候选。二、为什么用 MD5 查重判断重复文件不能只看文件名。因为相同内容的文件可能名字不同例如report.docx report - 副本.docx final-report.docx也不能只看大小。两个文件大小相同不代表内容相同。本项目采用两步判断先按文件大小分组只有大小相同的文件才可能重复。再对同大小文件计算 MD5MD5 相同则认为内容重复。核心逻辑在duplicate_finder.py中by_size:dict[int,list[Path]]defaultdict(list)forpathinpaths:by_size[path.stat().st_size].append(path)by_hash:dict[str,list[FileRecord]]defaultdict(list)forsize,same_size_pathsinby_size.items():iflen(same_size_paths)2:continueforpathinsame_size_paths:recordself._record_for(path,size)ifrecordisnotNone:by_hash[record.md5].append(record)这个设计能减少不必要的 MD5 计算。因为只有同大小文件才需要进一步计算哈希对于大量不重复文件来说会更快。MD5 计算采用分块读取避免大文件一次性读入内存defmd5_for_file(self,path:Path)-str:hasherhashlib.md5()withpath.open(rb)ashandle:forchunkiniter(lambda:handle.read(self.chunk_size),b):hasher.update(chunk)returnhasher.hexdigest()三、重复组排序策略用户最关心的通常是“能释放多少空间”所以扫描结果按文件大小从大到小排序returnsorted(groups,keylambdagroup:group.size,reverseTrue)每组内部则按修改时间从新到旧排序filestuple(sorted(records,keylambdaitem:item.modified_at,reverseTrue))因此界面中每组第一条是默认保留文件其余文件可以批量勾选删除。四、配置文件保存用户习惯配置使用 JSON 保存例如上次选择的文件夹、是否递归扫描、窗口大小等。dataclass(frozenTrue)classAppConfig:last_folder:strrecursive:boolTruekeep_strategy:strnewestwindow_width:int1180window_height:int760加载配置时如果文件不存在或 JSON 损坏就返回默认配置classmethoddefload(cls,path:Path)-AppConfig:ifnotpath.exists():returncls()try:datajson.loads(path.read_text(encodingutf-8))except(OSError,json.JSONDecodeError):returncls()valid{field:data[field]forfieldincls.__dataclass_fields__iffieldindata}returncls(**valid)这个处理比较稳健不会因为配置文件异常导致程序无法启动。五、SQLite保存扫描记录项目使用 SQLite 保存扫描会话和重复文件记录。数据库包含两张表scan_sessions记录扫描目录和扫描时间。duplicate_files记录每个重复文件的路径、大小、MD5、修改时间、是否保留、是否删除。建表逻辑如下CREATE TABLE IF NOT EXISTS scan_sessions(idINTEGER PRIMARY KEY AUTOINCREMENT,folder TEXT NOT NULL,scanned_at REAL NOT NULL)CREATE TABLE IF NOT EXISTS duplicate_files(idINTEGER PRIMARY KEY AUTOINCREMENT,session_id INTEGER NOT NULL,group_index INTEGER NOT NULL,md5 TEXT NOT NULL,path TEXT NOT NULL,size INTEGER NOT NULL,modified_at REAL NOT NULL,keep_file INTEGER NOT NULL,deleted INTEGER NOT NULL DEFAULT0,FOREIGN KEY(session_id)REFERENCES scan_sessions(id))保存扫描结果时会先插入一次扫描会话再插入每个文件记录session_idint(cursor.lastrowid)forgroup_index,groupinenumerate(groups,start1):keep_pathgroup.keep_file.pathforrecordingroup.files:conn.execute( INSERT INTO duplicate_files( session_id, group_index, md5, path, size, modified_at, keep_file ) VALUES (?, ?, ?, ?, ?, ?, ?) ,(session_id,group_index,group.md5,record.path,record.size,record.modified_at,1ifrecord.pathkeep_pathelse0,),)这里有一个细节数据库连接使用contextlib.closing明确关闭。Windows 下如果 SQLite 连接没有及时关闭可能导致数据库文件被占用测试或删除临时目录时会失败。六、wxPython 界面设计主界面由四部分组成顶部工具栏选择文件夹、递归选项、开始扫描、停止、批量勾选、清空勾选、删除所选。左侧列表显示重复文件。右侧预览显示图片、ZIP 内容或文件基本信息。底部状态栏显示已选数量、预计释放空间和扫描进度。列表使用wx.ListCtrlself.result_listwx.ListCtrl(list_panel,stylewx.LC_REPORT|wx.LC_SINGLE_SEL)ifhasattr(self.result_list,EnableCheckBoxes):self.result_list.EnableCheckBoxes(True)列设计如下columns[(组,56),(状态,80),(大小,90),(修改时间,150),(文件路径,520),(MD5,220),]这种布局适合工具类软件信息密度较高用户可以快速比较路径、大小和修改时间。七、扫描线程避免界面卡死文件扫描和 MD5 计算可能比较耗时如果直接在主线程执行GUI 会卡住。因此程序使用后台线程扫描self.scan_threadthreading.Thread(targetself._scan_worker,args(folder,self.recursive_checkbox.GetValue()),daemonTrue,)self.scan_thread.start()后台线程不能直接操作 wxPython 控件需要使用wx.CallAfter回到主线程更新界面progresslambdapath:wx.CallAfter(self.progress_label.SetLabel,f正在计算:{path})扫描完成后同样通过wx.CallAfter填充列表wx.CallAfter(self._scan_finished,session_id,rows)八、批量勾选和总大小统计用户可以点击“勾选重复项”程序会自动勾选每组中除保留文件以外的候选文件defon_select_duplicates(self,_event)-None:forindex,rowinenumerate(self.rows):ifhasattr(self.result_list,CheckItem):self.result_list.CheckItem(index,notrow[keep]andnotrow[deleted])self._update_selected_summary()统计已选文件路径def_selected_paths(self)-list[str]:paths[]ifnothasattr(self.result_list,IsItemChecked):returnpathsforindex,rowinenumerate(self.rows):ifself.result_list.IsItemChecked(index)andnotrow[keep]andnotrow[deleted]:paths.append(row[path])returnpaths统计预计释放空间def_selected_size(self)-int:selectedset(self._selected_paths())returnsum(row[size]forrowinself.rowsifrow[path]inselected)底部实时显示self.summary_label.SetLabel(f已选{len(paths)}个文件预计释放{format_size(total)})九、文件预览设计预览模块并不强行解析所有格式而是分层处理图片内置缩略图预览。ZIP读取压缩包文件列表。PDF、Word、Excel、视频显示文件基本信息并提供“打开文件”按钮。其他文件显示路径、大小、MIME 类型等基础信息。判断逻辑如下defbuild_preview(path:Path)-Preview:suffixpath.suffix.lower()ifsuffixinIMAGE_EXTENSIONS:returnPreview(image,_metadata_text(path),str(path))ifsuffix.zip:returnPreview(zip,_zip_text(path))ifsuffixinDOCUMENT_EXTENSIONS:returnPreview(document,_metadata_text(path)\n\n可使用“打开文件”调用系统默认程序查看。)ifsuffixinVIDEO_EXTENSIONS:returnPreview(video,_metadata_text(path)\n\n可使用“打开文件”调用系统默认播放器查看。)returnPreview(generic,_metadata_text(path))这种设计比较实用。Office、PDF、视频如果都做内嵌预览会引入很多依赖和兼容问题调用系统默认程序反而更稳定。十、删除安全放入回收站删除重复文件是高风险操作所以程序做了三层保护默认保留每组最新文件。删除前弹窗确认。删除时放入回收站而不是直接永久删除。确认框会显示删除数量和预计释放空间messagef确认将{len(paths)}个文件放入回收站\n预计释放空间{format_size(total)}ifwx.MessageBox(message,确认删除,wx.YES_NO|wx.NO_DEFAULT|wx.ICON_WARNING)!wx.YES:return回收站删除优先使用send2trashtry:fromsend2trashimportsend2trashexceptImportError:_windows_recycle(path)else:send2trash(path)如果没有安装send2trash则使用 Windows Shell API 作为备用方案operation.wFunc3operation.pFrompath\0\0operation.fFlags0x0040|0x0010|0x0400resultshell32.SHFileOperationW(ctypes.byref(operation))删除完成后数据库会标记文件状态defmark_deleted(self,paths:list[str])-None:ifnotpaths:returnwithclosing(self._connect())asconn:conn.executemany(UPDATE duplicate_files SET deleted 1 WHERE path ?,[(path,)forpathinpaths],)conn.commit()十一、启动脚本为了方便双击启动项目提供了start.batecho off cd /d %~dp0 python app.py if errorlevel 1 ( echo. echo Failed to start the application. echo Please check that Python and wxPython are installed. pause )cd /d %~dp0可以切换到 bat 文件所在目录避免双击运行时工作目录不正确。十二、测试验证项目使用 Python 自带的unittest做核心逻辑测试覆盖内容包括配置文件默认值和读写。MD5 重复文件分组。重复组按大小降序排序。每组默认保留最新文件。SQLite 保存和读取扫描结果。ZIP 和普通文件预览。回收站删除抽象。运行测试python-m unittest discover-s tests-v语法检查python-m py_compile app.py config.py database.py duplicate_finder.py models.py preview.py recycle.py检查 wxPythonpython-cimport wx; print(wxPython ok, wx.version())十三、运行方式安装依赖pip install wxPython send2trash启动程序python app.py或者双击start.bat总结这个项目虽然不大但包含了一个桌面工具常见的完整闭环GUI 交互后台耗时任务文件哈希计算SQLite 持久化配置保存文件预览安全删除单元测试其中最重要的设计点有三个先按大小分组再计算 MD5减少不必要的哈希计算。扫描线程和 GUI 线程分离避免界面卡死。删除进入回收站并二次确认降低误删风险。如果后续继续扩展可以考虑加入扫描历史管理、导出 Excel 报告、按文件类型筛选、忽略目录规则、多语言界面以及更强的预览能力。