三款Python命令行硬盘清理工具：临时文件、重复文件与目录分析

硬盘清理工具最怕的不是找不到而是找到之后不敢删。这次一口气拿到三款同类型的命令行小工具临时文件安全清理器、重复文件扫描器、大文件与目录分析器。它们有一个共同点——脚本代码不是人工从零敲出来的而是在大模型代码生成能力下批量产出的初版再由人来做代码审查、安全边界约束和实测验收。这个“基因”决定了它们和很多商业清理软件不一样不玩换肤、不搞“一键加速”、不做开机弹窗只解决三个最核心的问题——哪些临时文件可以清、哪些文件重复占空间、哪个目录或文件才是真正的空间大户。作为用来替代纯手工删除的辅助工具非常合适但你要做好心理准备它们本质上只是把“自动判断”的决策权交回给你而不是替你乱删东西。运行门槛可以说低到几乎没有任意一台近几年的普通 PC 就能跑不需要 GPU也不需要专用显存只要机器上有 Python 3.9 或更高版本Windows、Linux、macOS 都能运行。下面我把三份工具的完整实现、用法、测试流程和实测风险逐段拆开并且会把“为什么会这样写”“从哪里开始踩坑”一起说明白。如果你想自己验证效果建议先建一个测试目录复制一批测试文件进去然后再考虑对真实分区执行。1. 核心能力速览配置项说明项目类型本地 Python 命令行硬盘清理辅助脚本工具数量3 个分别是临时文件安全清理器、重复文件扫描器、大文件与目录分析器代码生产方式AI 生成主逻辑人工审查、加安全参数主要功能过期临时文件清理、重复文件检测、大文件与大目录占位分析运行环境Windows / Linux / macOS需 Python 3.9仅使用标准库硬件门槛无 GPU 要求CPU 与磁盘即可运行显存需求无这类工具不涉及模型推理启动方式命令行启动按参数指定目标目录、策略和输出文件图形界面无 GUI终端输出结果接口服务未做 Web API可被更上层工具或定时任务直接调用批量能力支持目录递归批量处理可接入批处理脚本安全机制默认输出预览结果删除操作必须显式加 --delete适合场景本地电脑空间清理、日常维护脚本、异常磁盘占位定位从能力速览能看出来这套工具适合“有基本命令行经验的人”。它们不会像商业软件那样扫描注册表和系统服务也不会试图去清理“所有垃圾”。定位非常克制只扫你指定的目录只处理你指定的规则是否真正删除由你确认。2. 适用场景与使用边界2.1 适用场景最典型的用法是 C 盘或项目磁盘告警时先用大文件与目录分析器扫一遍看看究竟是“单个文件超大”还是“某个目录里小文件太多”。定位到嫌疑目录后再用重复文件扫描器找同内容副本最后针对*.tmp、*.log、*.bak这类过期临时文件执行安全清理。三段式配合比单点删除工具更完整。第二个典型场景是批量维护。机器上有多个开发目录、备份目录或下载目录人工一个个看太慢。这三款工具都是用标准库写的命令丢进批处理脚本或者定时任务都可以输出也能重定向到文本日志。清理临时文件时模块化命令行天然适合“每周定时扫一次旧日志”的场景。第三个场景是代码学习与二次开发。脚本结构不长不依赖私有库读一遍就能理解文件扫描、哈希去重、目录占位统计的基本实现方式。如果你正在学 Python 文件系统操作这算是不错的样例集。2.2 安全边界再说清楚一点这组工具做的是“删除辅助”不是“无脑自动清理”。AI 生成的代码能帮你遍历目录、比较文件、筛选旧文件但它不知道哪些正在被进程占用也不知道哪些对你重要。最终决定权必须留在人手里。所以这里有几条硬性约束清理目标不要直接指向C:\Windows、/System、程序安装目录等系统目录。默认删除操作必须靠--delete参数开启不给参数时只输出预览。执行真实删除前先在测试目录用副本验证一遍。重复文件扫描只定位重复项默认不删除任何文件。涉及他人文件、公司共享目录、资料库时先确认文件授权和备份策略。如果你没有把握更稳妥的做法是分析归类后用移动命令把候选文件移到“待删除”目录过几天确认无误再统一清空。3. 环境准备与前置条件这组脚本不依赖第三方包因此不需要pip install任何库。但你需要确认本机 Python 版本打开终端执行python --version如果你的机器安装的是python3命令则换成python3 --versionWindows 用户可以在 PowerShell 或 CMD 中运行Linux/macOS 用户直接在终端运行。建议使用 Python 3.9 以上版本主要是为了使用pathlib.Path.rglob和类型标注语法低版本兼容起来反而麻烦。接下来准备一个测试目录。不要一上来就扫整个硬盘先做一组小规模验证$base C:\tool_test New-Item -ItemType Directory -Force -Path $base\temp, $base\dups, $base\big | Out-Null Set-Content -Path $base\temp\old.log -Value old file Set-Content -Path $base\temp\new.log -Value new file Set-Content -Path $base\dups\a.txt -Value same content Copy-Item $base\dups\a.txt $base\dups\a-copy.txt $bigBytes New-Object byte[] (2 * 1024 * 1024) [IO.File]::WriteAllBytes($base\dups\big.bin, $bigBytes) Copy-Item $base\dups\big.bin $base\dups\big-copy.bin $largeBytes New-Object byte[] (5 * 1024 * 1024) [IO.File]::WriteAllBytes($base\big\large.bin, $largeBytes)这样我们就有了一个包含旧日志、新日志、文本重复文件、二进制重复文件和一个 5MB 大文件的测试数据目录。后文的验证全部基于这个测试目录体系跑通后再换真实数据。4. 工具一临时文件安全清理器4.1 设计思路临时文件清理工具的难点不是怎么写遍历而是怎么保证不把不该删的删掉。AI 初版代码很容易“很能干”扫到一个 tmp 后缀就删一个。这个逻辑看起来很高效但实际风险很高因为很多软件正在使用的临时文件也有.tmp后缀而且时间戳不一定能代表是否安全。我保留的核心逻辑是这样一条链指定目录 → 递归匹配后缀模式 → 校验文件修改时间 → 默认先预览加--delete才执行删除。判断是否过期只依赖文件最后修改时间不碰注册表也不猜哪些软件在用。即便删错也只影响该目录下符合规则的旧文件不会扩散到无关区域。4.2 完整代码将下面代码保存为temp_cleaner.py#!/usr/bin/env python3 临时文件安全清理器 默认只预览不删除必须显式指定 --delete 才会执行删除。 用法示例: python temp_cleaner.py --target ./temp --pattern *.tmp --older-than 7 python temp_cleaner.py --target ./temp --pattern *.log --older-than 7 --delete import argparse import time from pathlib import Path SENSITIVE_DIR_KEYS ( windows, system32, program files, /system/, /etc/, /usr/, /bin/ ) def collect_expired_files(root: Path, pattern: str, older_than_days: float): now time.time() expires_before now - older_than_days * 86400 matched [] for file_path in root.rglob(pattern): if not file_path.is_file(): continue try: mtime file_path.stat().st_mtime except OSError: continue if mtime expires_before: matched.append(file_path) return matched def main(): parser argparse.ArgumentParser(description清理指定目录下的过期临时文件) parser.add_argument(--target, requiredTrue, help要扫描的目标目录) parser.add_argument(--pattern, default*.tmp, help文件后缀匹配模式) parser.add_argument(--older-than, typefloat, default30.0, help只处理修改时间超过多少天的文件) parser.add_argument(--delete, actionstore_true, help确认删除缺省只输出预览) args parser.parse_args() target Path(args.target).resolve() target_text str(target).lower() if any(key in target_text for key in SENSITIVE_DIR_KEYS): raise SystemExit(检测到敏感系统目录请重新指定清理目录。) if not target.exists() or not target.is_dir(): raise SystemExit(f目标目录不存在或不是文件夹: {target}) files collect_expired_files(target, args.pattern, args.older_than) print(f匹配文件数: {len(files)}) if not args.delete: for f in files[:100]: print(f[预览] {f}) if len(files) 100: print(f... 其余 {len(files) - 100} 个文件未显示) print(当前为预览模式未删除任何文件。加入 --delete 才会执行删除。) return for f in files: try: f.unlink() print(f[已删除] {f}) except PermissionError: print(f[跳过/无权限] {f}) except OSError as exc: print(f[跳过/异常] {f}: {exc}) if __name__ __main__: main()代码里做了一个“敏感目录”的简单拦截防止用户不小心把目标指到系统目录。它不是万能防线只是降低误操作概率的提醒。真正防误删的主力仍然是默认预览这个行为习惯。4.3 使用方法与预期输出先跑一次预览python temp_cleaner.py --target C:\tool_test\temp --pattern *.log --older-than 0这里的--older-than 0表示“只要修改时间在当前时间之前的都算候选”。测试阶段用 0 天比较方便实际使用建议改成 7 或 30 天。预期输出类似匹配文件数: 2 [预览] C:\tool_test\temp\old.log [预览] C:\tool_test\temp\new.log 当前为预览模式未删除任何文件。加入 --delete 才会执行删除。两个 log 文件都会被匹配到因为这批文件都是刚创建的且“修改时间早于当前时间”这一条件成立。确认预览列表没问题后再执行真实清理python temp_cleaner.py --target C:\tool_test\temp --pattern *.log --older-than 0 --delete执行完成后再跑一次预览模式匹配文件数会变成 0。这就是判断工具是否正常工作的标准。权限问题方面Windows 下如果文件被某进程锁定会输出“跳过/无权限”Linux/macOS 下如果当前用户没有目录写权限也会出现类似提示。5. 工具二重复文件扫描器5.1 设计思路重复文件扫描器的常规思路是先按文件大小分组再把大小相同的文件拿出来做哈希比较。如果一开始就把目录里所有文件都做全量哈希性能会很差大部分不同文件的大小本身就不一样没必要进入哈希阶段。AI 初版只做了“文件大小一致就判定重复”这会误伤大量恰好相同大小的正常文件。修订后加了两层判断第一层按文件大小粗筛第二层对候选文件计算 SHA-256只有内容哈希一致才判定为重复。代码默认只输出 JSON 报告不删除文件。谁留谁删还是由人工决定。5.2 完整代码将下面代码保存为dup_finder.py#!/usr/bin/env python3 重复文件扫描器 只输出重复文件报告不删除文件。 用法示例: python dup_finder.py --target ./data --min-size-mb 1 --json-out dup.json import argparse import hashlib import json from collections import defaultdict from pathlib import Path CHUNK_SIZE 1024 * 1024 def file_sha256(path: Path): h hashlib.sha256() with open(path, rb) as f: while True: block f.read(CHUNK_SIZE) if not block: break h.update(block) return h.hexdigest() def collect_candidates(root: Path, min_size_mb: float): min_bytes int(min_size_mb * 1024 * 1024) size_to_paths defaultdict(list) for path in root.rglob(*): if not path.is_file(): continue try: size path.stat().st_size except OSError: continue if size min_bytes: size_to_paths[size].append(path) return {size: paths for size, paths in size_to_paths.items() if len(paths) 1} def find_duplicates(root: Path, min_size_mb: float): result [] for size, paths in collect_candidates(root, min_size_mb).items(): hash_map defaultdict(list) for path in paths: try: digest file_sha256(path) except OSError: continue hash_map[digest].append(str(path)) for digest, same_paths in hash_map.items(): if len(same_paths) 1: result.append({ size: size, sha256: digest, files: same_paths }) return result def main(): parser argparse.ArgumentParser(description扫描指定目录内的重复文件) parser.add_argument(--target, requiredTrue, help目标目录) parser.add_argument(--min-size-mb, typefloat, default1.0, help只扫描大于等于该 MB 大小的文件) parser.add_argument(--json-out, defaultduplicates.json, help报告输出路径) args parser.parse_args() target Path(args.target).resolve() if not target.exists() or not target.is_dir(): raise SystemExit(f目标目录不存在或不是文件夹: {target}) duplicates find_duplicates(target, args.min_size_mb) with open(args.json_out, w, encodingutf-8) as fp: json.dump(duplicates, fp, ensure_asciiFalse, indent2) total_files sum(len(item[files]) for item in duplicates) total_saved sum((len(item[files]) - 1) * item[size] for item in duplicates) print(f重复组数: {len(duplicates)}) print(f涉及文件数: {total_files}) print(f预计可释放空间: {total_saved / 1024 / 1024:.2f} MB) print(f报告输出到: {args.json_out}) if __name__ __main__: main()5.3 使用方法与预期输出扫描测试目录python dup_finder.py --target C:\tool_test\dups --min-size-mb 0.000001 --json-out dup_report.json因为测试文件都不大所以要把最小阈值调得很低。实际使用时阈值可以设成 1MB、10MB 或更高扫描速度会更快。预期输出类似重复组数: 2 涉及文件数: 4 预计可释放空间: 2.13 MB 报告输出到: dup_report.json打开dup_report.json会看到重复组和文件路径{ size: 2097152, sha256: 一串64位哈希, files: [ C:\\tool_test\\dups\\big.bin, C:\\tool_test\\dups\\big-copy.bin ] }这个 JSON 报告就是后续人工处置的依据。如果只是几个测试文件可以直接保留一个删一个如果面对上百 GB 的素材库建议先把 JSON 报告导入表格工具按重复文件路径和大小排列后再决定保留策略。涉及版权素材或公司资料时想清楚保留哪一份、删除哪一份都需要先确认授权和用途。6. 工具三大文件与目录分析器6.1 设计思路第三款工具解决“空间到底被谁占了”。实现上最容易出错的问题是重复遍历如果对每个一级子目录都分别调用一次os.walk会出现同一个深层目录被反复访问很多次目录树越大越慢。AI 初版就犯了这类问题。修订后的版本改为单次遍历os.walk只走一遍目标目录同时统计每个一级子目录的大小并记录所有文件中的 Top N。这样既能看到目录维度的占用也能看到文件维度的占用。输出带上人类可读的单位比如GB和MB避免一长串字节看着头晕。6.2 完整代码将下面代码保存为disk_survey.py#!/usr/bin/env python3 大文件与目录分析器 单次遍历目标目录输出一级目录占用 Top N 和文件占用 Top N。 用法示例: python disk_survey.py --target ./data --top-dirs 20 --top-files 20 import argparse import os from pathlib import Path def human_size(num: float) - str: for unit in (B, KB, MB, GB, TB): if num 1024: return f{num:.1f} {unit} num / 1024 return f{num:.1f} PB def main(): parser argparse.ArgumentParser(description分析目录占用空间) parser.add_argument(--target, requiredTrue, help目标文件或目录) parser.add_argument(--top-dirs, typeint, default20, help显示多少个目录) parser.add_argument(--top-files, typeint, default30, help显示多少个文件) args parser.parse_args() target Path(args.target).resolve() if not target.exists(): raise SystemExit(f路径不存在: {target}) if target.is_file(): print(f{human_size(target.stat().st_size)} {target}) return dir_sizes {} all_files [] for root, _, files in os.walk(target, followlinksFalse): root_path Path(root) for name in files: full_path root_path / name try: size full_path.stat().st_size except OSError: continue all_files.append((full_path, size)) relative_parts full_path.relative_to(target).parts if len(relative_parts) 1: top_dir target / relative_parts[0] dir_sizes[top_dir] dir_sizes.get(top_dir, 0) size dir_ranking sorted(dir_sizes.items(), keylambda item: item[1], reverseTrue)[:args.top_dirs] all_files.sort(keylambda item: item[1], reverseTrue) file_ranking all_files[:args.top_files] print(一级目录占用 TOP:) if dir_ranking: for path, size in dir_ranking: print(f{human_size(size):10} {path}) else: print( (目标下没有子目录)) print(文件占用 TOP:) if file_ranking: for path, size in file_ranking: print(f{human_size(size):10} {path}) else: print( (目标下没有文件)) if __name__ __main__: main()要注意的是这版工具只统计“以目标目录为根”的相对占用因此顶层子目录如果是一个挂载得非常深的路径输出时仍保持原始路径。Windows 下如果目标目录包含隐藏目录或系统符号链接followlinksFalse会避免跟随链接继续向下扫描可以降低递归进循环目录的风险。6.3 使用方法与预期输出分析整个测试目录python disk_survey.py --target C:\tool_test --top-dirs 10 --top-files 10预期输出类似一级目录占用 TOP: 5.0 MB C:\tool_test\big 4.0 MB C:\tool_test\dups 3.0 KB C:\tool_test\temp 文件占用 TOP: 5.0 MB C:\tool_test\big\large.bin 2.0 MB C:\tool_test\dups\big-copy.bin 2.0 MB C:\tool_test\dups\big.bin这个结果能直接告诉你如果现在空间紧张最值得处理的不是temp目录那几 KB而是big目录或者dups里的重复大文件。把大文件分析和重复扫描结合起来你会形成一条比较靠谱的硬盘清理路径。7. 实测流程与效果验证7.1 测试准备与用例测试需要在隔离目录内执行不要直接指向真实分区。上面已经用 PowerShell 创建了C:\tool_test结构如下目录内容测试点temp两个日志文件临时文件清理预览与删除dups两对重复文件同内容文件检测big一个 5MB 文件大文件目录统计7.2 测试步骤第一步运行大文件分析工具确认它能正确识别各目录占用。这一步不需要删除任何数据只要看输出排名是否正确。第二步运行重复文件扫描器确认它能找出两对重复文件并生成dup_report.json。第三步运行临时文件安全清理器但不加--delete确认预览模式会输出两个日志文件且目录中文件依然存在。第四步重复第三步这次加上--delete确认日志文件被删除其他目录里的测试文件不受影响。7.3 判断标准预览模式输出匹配数量与真实文件数量一致。重复文件报告里能正确列出a.txt与a-copy.txt、big.bin与big-copy.bin。加了--delete之后只有匹配到的*.log文件消失dups和big目录下的文件不受影响。遇到权限受限的文件时工具会打印跳过信息而不是直接崩溃。大文件分析工具不会因为某个文件被占用而中断整个目录扫描。如果在测试过程中发现脚本输出的路径是拼接错乱的通常是因为 Windows 命令行反斜杠与Path解析混用。解决办法是执行命令时给路径加双引号。如果出现中文字符乱码Windows 下可在 PowerShell 临时执行$OutputEncoding [Console]::OutputEncoding [Text.UTF8Encoding]::new()再运行脚本。8. 资源占用与性能观察这三款工具都不碰 GPU所以不要用“显存占用”来评价它们。真正的资源瓶颈在 CPU、磁盘 IO 和内存占用三者比重取决于扫描目录规模。大文件分析器以目录遍历为主路径数量越多磁盘 IO 越频繁重复文件扫描器在 IO 基础上还会对候选文件做 SHA-256 哈希计算CPU 占用会明显提高。临时文件清理器相对最轻因为只遍历一次并按文件名模式和修改时间过滤。观察方式很直接跑任务时打开任务管理器或系统监视器看进程 CPU 使用率、内存占用和磁盘活动。小目录通常几秒内完成几十 GB 的大目录可能要几分钟尤其是机械硬盘或混杂大量小文件的目录。更稳妥的判断是先扫一层目录验证输出后再扫完整目录。降低负载有几种做法把目标从整个盘收窄到某个嫌疑目录。重复文件扫描时调高--min-size-mb跳过大量小文件让哈希计算集中在大文件上。清理临时文件时把--older-than从 0 改成 30减少候选文件数。不要在业务高峰期对共享存储或生产服务器执行全盘扫描。9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动报python 不是内部或外部命令Python 未安装或未加入 PATH执行python --version安装 Python 并勾选 Add to PATH提示目标目录不存在路径输入错误或目录不存在检查Path是否存在更正路径路径含空格时加双引号脚本在 Windows 下中文乱码终端默认编码不是 UTF-8查看输出字符设置终端为 UTF-8 或调整输出编码临时清理器不删除文件没加--delete查看提示文字确认预览后加入--delete删除时报无权限文件被进程占用或当前用户权限不足查看错误对应的具体文件关闭占用程序或调整目录写权限重复文件扫描找不到重复项文件小于--min-size-mb阈值查看报告日志调低阈值或改用默认值后重新测试扫描速度很慢目录内文件量太大或哈希计算过多观察任务管理器 IO/CPU收窄扫描目录调高最小大小阈值大目录分析器输出大小不对劲符号链接导致的重复遍历或权限跳过检查followlinks和输出路径避免对程序目录和系统目录直接扫描删完后磁盘占用没有明显下降文件被占用但未提示或大量文件在回收站中重新执行大文件分析器看排名检查回收站确认实际文件是否仍被进程占用排查工具问题时有一个通用原则先加--delete前跑一遍预览先小范围验证再放大范围。这样即使出错影响也是局部的。10. 批量任务与自动化思路本套工具没有设计 Web API但命令行本身就是很好的批处理接口。可以将三款工具嵌入到批处理或定时任务中完成“定时扫描→输出报告→人工确认清理”半自动链路。最简单的脚本化方式是在 PowerShell 里依次执行$target C:\tool_test python .\disk_survey.py --target $target --top-dirs 20 --top-files 30 python .\dup_finder.py --target $target --min-size-mb 50 --json-out C:\tool_test\dup_report.json python .\temp_cleaner.py --target C:\tool_test\temp --pattern *.log --older-than 30这条链路的输出分别是目录占用报告、重复文件报告和临时文件预览。把结果重定向到带时间戳的文件就能形成历史记录python .\disk_survey.py --target $target --top-dirs 20 --top-files 30 | Out-File -FilePath C:\log\disk_survey_$(Get-Date -Format yyyyMMdd).txt如果要接入定时任务Windows 可以使用任务计划程序Linux 可以使用 cron。定时任务里只建议运行“预览模式”和“报告生成”命令不建议把带--delete的清理命令直接无人值守执行。因为临时文件和重复文件是否可删经常需要业务上下文判断无人值守自动删除一旦误判恢复成本往往高于省下的那点空间。11. 最佳实践与使用建议先说最值得做的第一步把三个脚本保存到单独目录建立统一的inputs、outputs、logs目录结构脚本路径、目标目录、报告输出都写成统一路径变量避免每次敲错。下一步才是生成测试数据、跑通预览模式。真实清理时保留一份“最小可运行配置”。比如临时文件清理器只清理某个明确目录下的*.log和*.tmp重复文件扫描器只处理“大于 100MB 且不超过指定目录”的文件。小范围稳定之后再把范围缓慢扩展到下一个目录。关于删除动作我的建议是“两段式”第一段把所有候选文件移动到“待删除”文件夹而不是直接unlink第二段等待一天或一周确认系统运行正常后再清空“待删除”文件夹。这个思路能显著降低误删风险尤其是面对名称相似、位置分散的重复文件时。对于涉及人脸照片、音视频素材、公司内部文档的数据目录删除前必须先确认授权和备份策略。即使文件内容是重复的也不能假设哪一份副本可以被直接删除不同文件夹下的同名副本可能被不同的流程引用。发布或商用前的资料清理尽量由业务负责人确认后再执行。最后提一句容易被忽略的如果重复文件报告显示某个目录内存在大量同名副本不要只想着删先看是不是项目同步工具、备份策略或下载逻辑导致的重复写入。工具只能告诉你结果背后的原因需要结合业务来判断。如果你是第一次使用这类工具建议先收藏备用动手前把测试目录跑通再逐步过渡到真实环境。