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

硬盘清理工具最怕的不是找不到，而是找到之后不敢删。这次一口气拿到三款同类型的命令行小工具：临时文件安全清理器、重复文件扫描器、大文件与目录分析器。它们有一个共同点——脚本代码不是人工从零敲出来的，而是在大模型代码生成能力下批量产出的初版，再由人来做代码审查、安全边界约束和实测验收。

这个“基因”决定了它们和很多商业清理软件不一样：不玩换肤、不搞“一键加速”、不做开机弹窗，只解决三个最核心的问题——哪些临时文件可以清、哪些文件重复占空间、哪个目录或文件才是真正的空间大户。作为用来替代纯手工删除的辅助工具非常合适，但你要做好心理准备：它们本质上只是把“自动判断”的决策权交回给你，而不是替你乱删东西。

运行门槛可以说低到几乎没有：任意一台近几年的普通 PC 就能跑，不需要 GPU，也不需要专用显存，只要机器上有 Python 3.9 或更高版本，Windows、Linux、macOS 都能运行。下面我把三份工具的完整实现、用法、测试流程和实测风险逐段拆开，并且会把“为什么会这样写”“从哪里开始踩坑”一起说明白。如果你想自己验证效果，建议先建一个测试目录，复制一批测试文件进去，然后再考虑对真实分区执行。

1. 核心能力速览

从能力速览能看出来，这套工具适合“有基本命令行经验的人”。它们不会像商业软件那样扫描注册表和系统服务，也不会试图去清理“所有垃圾”。定位非常克制：只扫你指定的目录，只处理你指定的规则，是否真正删除由你确认。

2. 适用场景与使用边界

2.1 适用场景

最典型的用法是 C 盘或项目磁盘告警时，先用大文件与目录分析器扫一遍，看看究竟是“单个文件超大”还是“某个目录里小文件太多”。定位到嫌疑目录后，再用重复文件扫描器找同内容副本；最后针对*.tmp、*.log、*.bak这类过期临时文件执行安全清理。三段式配合，比单点删除工具更完整。

第二个典型场景是批量维护。机器上有多个开发目录、备份目录或下载目录，人工一个个看太慢。这三款工具都是用标准库写的命令，丢进批处理脚本或者定时任务都可以，输出也能重定向到文本日志。清理临时文件时，模块化命令行天然适合“每周定时扫一次旧日志”的场景。

第三个场景是代码学习与二次开发。脚本结构不长，不依赖私有库，读一遍就能理解文件扫描、哈希去重、目录占位统计的基本实现方式。如果你正在学 Python 文件系统操作，这算是不错的样例集。

2.2 安全边界

再说清楚一点：这组工具做的是“删除辅助”，不是“无脑自动清理”。AI 生成的代码能帮你遍历目录、比较文件、筛选旧文件，但它不知道哪些正在被进程占用，也不知道哪些对你重要。最终决定权必须留在人手里。

所以这里有几条硬性约束：

• 清理目标不要直接指向C:\Windows、/System、程序安装目录等系统目录。
• 默认删除操作必须靠--delete参数开启，不给参数时只输出预览。
• 执行真实删除前，先在测试目录用副本验证一遍。
• 重复文件扫描只定位重复项，默认不删除任何文件。
• 涉及他人文件、公司共享目录、资料库时，先确认文件授权和备份策略。

如果你没有把握，更稳妥的做法是：分析归类后，用移动命令把候选文件移到“待删除”目录，过几天确认无误再统一清空。

3. 环境准备与前置条件

这组脚本不依赖第三方包，因此不需要pip install任何库。但你需要确认本机 Python 版本，打开终端执行：

python --version

如果你的机器安装的是python3命令，则换成：

python3 --version

Windows 用户可以在 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", required=True, help="要扫描的目标目录") parser.add_argument("--pattern", default="*.tmp", help="文件后缀匹配模式") parser.add_argument("--older-than", type=float, default=30.0, help="只处理修改时间超过多少天的文件") parser.add_argument("--delete", action="store_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", required=True, help="目标目录") parser.add_argument("--min-size-mb", type=float, default=1.0, help="只扫描大于等于该 MB 大小的文件") parser.add_argument("--json-out", default="duplicates.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", encoding="utf-8") as fp: json.dump(duplicates, fp, ensure_ascii=False, indent=2) 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", required=True, help="目标文件或目录") parser.add_argument("--top-dirs", type=int, default=20, help="显示多少个目录") parser.add_argument("--top-files", type=int, default=30, 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, followlinks=False): 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(), key=lambda item: item[1], reverse=True)[:args.top_dirs] all_files.sort(key=lambda item: item[1], reverse=True) 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 下如果目标目录包含隐藏目录或系统符号链接，followlinks=False会避免跟随链接继续向下扫描，可以降低递归进循环目录的风险。

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，结构如下：

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. 常见问题与排查方法

排查工具问题时有一个通用原则：先加--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；第二段等待一天或一周，确认系统运行正常后再清空“待删除”文件夹。这个思路能显著降低误删风险，尤其是面对名称相似、位置分散的重复文件时。

对于涉及人脸照片、音视频素材、公司内部文档的数据目录，删除前必须先确认授权和备份策略。即使文件内容是重复的，也不能假设哪一份副本可以被直接删除：不同文件夹下的同名副本可能被不同的流程引用。发布或商用前的资料清理，尽量由业务负责人确认后再执行。

最后提一句容易被忽略的：如果重复文件报告显示某个目录内存在大量同名副本，不要只想着删，先看是不是项目同步工具、备份策略或下载逻辑导致的重复写入。工具只能告诉你结果，背后的原因需要结合业务来判断。如果你是第一次使用这类工具，建议先收藏备用，动手前把测试目录跑通，再逐步过渡到真实环境。