Python 写一个文件夹清理小工具：按体积、天数和白名单安全删除临时文件

项目跑久了，临时文件不会一下子占满磁盘，只会慢慢累积：__pycache__、旧日志、测试产出物、构建缓存，平时看着占不了多少空间，等CI机器或者开发环境弹出空间不足提示再动手清理，就很被动了。用Python写一个轻量的文件夹清理小工具，真正要做好的核心点从来不是“能删掉文件”，而是先把文件夹占用空间算清楚、按预设规则筛选待清理的候选文件、先提供试运行预览，再通过白名单和二次确认机制保障删除操作安全。

先把这个小工具的适用边界定清楚

这个工具只做一件事：清理指定文件夹下明确可以丢弃的临时文件。它不会操作数据库、不会处理业务侧上传的文件，也不会碰用户手动保存的个人资料。边界定义得越小，脚本越容易验证可用性，也越不容易出现误删问题。

我们先给它设定三个默认规则：只处理你指定的根文件夹、默认保留最近7天内生成的文件、默认跳过.git、.venv、node_modules这类特殊文件夹。它的主要清理对象放在Python项目常见的缓存文件上，比如__pycache__、.pytest_cache、.mypy_cache，以及你明确传入的待清理旧日志后缀。

搭建最小可运行的命令行项目

这个工具的项目结构可以非常简单，先新建一个文件clean_temp.py。全程只用Python标准库实现，不需要额外安装第三方依赖，后续放到开发机、CI机器或者容器里都可以直接运行，适配性很强。

mkdir py-cleaner
cd py-cleaner
touch clean_temp.py
python3 --version

如果你的机器上同时安装了多个Python版本，建议先确认python3指向的版本号。这个脚本没有用到太新的语法特性，Python 3.9以上的版本基本都能直接跑通；团队内部使用的话，可以把适配版本写进README或者CI镜像说明里，避免其他人拿到脚本运行才发现命令不兼容。

用 os.walk 扫描文件夹并跳过白名单

扫描文件夹的时候，最关键的一步就是主动绕过白名单路径。很多误删事故的根源从来不是删除逻辑写得太复杂，而是递归扫描一开始就进入了不该操作的文件夹。os.walk的dirs列表支持原地修改，我们可以直接通过这个特性把白名单文件夹从递归遍历的路径里剔除掉。

from pathlib import Path
import os
import time

SKIP_DIRS = {".git", ".venv", "node_modules"}
CACHE_DIRS = {"__pycache__", ".pytest_cache", ".mypy_cache"}

def iter_candidates(root: Path, keep_days: int):
    now = time.time()
    expire_seconds = keep_days * 24 * 60 * 60

    for current, dirs, files in os.walk(root):
        dirs[:] = [name for name in dirs if name not in SKIP_DIRS]
        current_path = Path(current)

        in_cache_dir = any(part in CACHE_DIRS for part in current_path.parts)

        for name in files:
            path = current_path / name
            try:
                stat = path.stat()
            except OSError:
                continue

            is_old_enough = now - stat.st_mtime > expire_seconds
            is_temp_file = name.endswith((".pyc", ".pyo", ".log.1", ".tmp"))

            if is_old_enough and (in_cache_dir or is_temp_file):
                yield path, stat.st_size

这里没有把全部.log后缀纳入默认清理规则，是因为很多服务会持续向当前日志文件写入内容。更稳妥的做法是只清理轮转后的归档旧日志，比如.log.1，或者让使用者显式传入自己要清理的文件后缀。脚本默认逻辑越保守、需要开放权限的操作越要手动确认，上线使用的时候就越不容易出问题。

给脚本加上空间阈值判断和试运行能力

只按文件生成时间判断要不要删还不够。有些文件夹里的旧缓存总大小只有几十MB，完全没必要每次运行都处理；有些文件夹体积已经涨到8GB，才真正需要进入清理流程。我们可以给脚本加一个占用体积阈值：低于阈值的时候只打印当前状态，高于阈值的时候才列出来所有待清理的候选文件。

def scan_total_size(root: Path) -> int:
    total = 0
    for current, dirs, files in os.walk(root):
        dirs[:] = [name for name in dirs if name not in SKIP_DIRS]
        current_path = Path(current)
        for name in files:
            path = current_path / name
            try:
                total += path.stat().st_size
            except OSError:
                continue
    return total

def format_size(size: int) -> str:
    value = float(size)
    for unit in ["B", "KB", "MB", "GB"]:
        if value 

把空间统计和候选文件扫描拆成两个独立函数，逻辑会更清晰方便排查问题。第一次扫描只需要得出结论“这个文件夹有没有必要清理”，第二次扫描才会筛选出“哪些文件可以被清理”。后续你如果想把统计结果对接告警或者日常报表，也可以直接复用空间统计函数。

补齐命令行参数和删除确认逻辑

命令行入口的设计思路是把风险操作放到显式参数里。默认试运行模式只会打印候选文件列表和预计能释放的空间大小，只有额外加上--delete参数的时候，才会实际执行删除操作。这样脚本第一次在陌生文件夹运行的时候，操作风险会低很多。

import argparse

def main():
    parser = argparse.ArgumentParser(description="Clean old temporary files safely.")
    parser.add_argument("root", help="target directory")
    parser.add_argument("--keep-days", type=int, default=7)
    parser.add_argument("--limit-gb", type=float, default=5.0)
    parser.add_argument("--delete", action="store_true")
    args = parser.parse_args()

    root = Path(args.root).resolve()
    if not root.exists() or not root.is_dir():
        raise SystemExit(f"not a directory: {root}")

    total_size = scan_total_size(root)
    limit_size = int(args.limit_gb * 1024 * 1024 * 1024)
    print(f"文件夹占用：{format_size(total_size)}，阈值：{args.limit_gb:.1f}GB")

    if total_size 8}  {path}")

    print(f"候选文件：{len(candidates)} 个，预计释放：{format_size(release_size)}")

    if not args.delete:
        print("当前为试运行模式；确认无误后再加 --delete。")
        return

    for path, _ in candidates:
        try:
            path.unlink()
        except OSError as error:
            print(f"删除失败：{path}，原因：{error}")

if __name__ == "__main__":
    main()

这里还有一个细节：脚本只会单独删除文件，不会直接递归删除整个文件夹。缓存文件清空之后可能会留下空文件夹，但是这个处理逻辑比直接删除整段文件夹安全很多。如果确实需要清理所有空文件夹，可以单独新增一个开关，并且放在文件删除逻辑全部执行完毕之后再运行。

本地实测一遍，确认输出符合预期

第一次运行的时候建议先找一个专门的测试文件夹，手动往里面放几个修改时间较早的文件，再运行脚本看输出结果。不要一开始就直接操作工作区根文件夹或者服务器的日志存储路径。

mkdir -p demo/__pycache__
touch demo/__pycache__/old.pyc
python3 clean_temp.py demo --keep-days 0 --limit-gb 0.001
python3 clean_temp.py demo --keep-days 0 --limit-gb 0.001 --delete

正常运行的情况下，不带删除参数的命令只会打印候选文件信息和预计释放空间，带了删除参数的命令才会真正删掉候选文件。这个验证流程虽然简单，但是可以完整覆盖“阈值判断、候选筛选、试运行预览、删除确认”四个核心环节。要放到团队内公开使用之前，也可以把这几条验证命令改成轻量的自动化用例。

接入定时任务的时候要保留完整运行日志

如果只是手动运行脚本，输出结果直接展示在终端里就够了；一旦对接了定时任务，就需要把所有运行记录都留存下来。至少要记录本次扫描的文件夹路径、文件夹总占用大小、待清理文件的数量、预计释放空间和删除失败的文件清单。后续如果出现异常疑问，可以直接回溯脚本当时的所有操作记录。

0 3 * * * /usr/bin/python3 /opt/tools/clean_temp.py /data/build-cache --limit-gb 20 --keep-days 10 --delete >> /var/log/clean-temp.log 2>&1

如果这个脚本部署在CI机器上，更推荐先跑一周的试运行模式，确认所有日志输出都符合预期之后，再加上--delete参数开启实际删除。清理脚本的核心指标从来不是清理效率有多高，能稳定释放冗余空间，同时每一次操作的记录都清晰可查，才适合长期后台运行。

常见问题

为什么默认不直接删除所有 .log 文件？

当前正在写入的日志文件还会被服务持续调用，直接删除会影响问题排查和日志轮转流程正常运行。更稳妥的方案是只清理轮转归档后的旧日志，或者让使用的人明确传入自己要清理的后缀规则。

为什么必须先执行试运行？

试运行模式可以提前展示所有待清理的文件、总数量和预计释放空间，相当于在删除前给了人工最后一次确认的机会。尤其是第一次在陌生路径运行脚本的时候，这一步可以拦截掉很多参数配置错误的问题。

文件夹占用体积低于阈值的时候还要扫描候选文件吗？

通常不需要。体积低于阈值说明清理带来的收益非常有限，只打印当前体积状态就足够了。等文件夹总占用超过阈值之后，再启动候选文件扫描，脚本本身的运行开销也会更低。

这个工具适合清理用户上传的文件吗？

不适合。用户上传的文件通常对应业务归属、审计要求和特定的恢复流程，需要走专门的归档或者生命周期管理策略。这个脚本只适合清理缓存、临时文件和明确可以丢弃的构建产出物。

小结

一个好用的Python文件夹清理工具，设计思路不应该从删除动作开始，而是先定义适用边界、空间阈值、候选筛选规则和操作确认机制。先统计文件夹总占用体积，再通过白名单规则和文件创建时间筛选待清理内容，默认开启试运行，确认所有规则符合预期之后再执行实际删除，这套流程看起来多走了几步，其实是在给脚本加上足够的安全防护。把运行日志和定时任务配置好之后，它就可以作为开发环境、CI机器和构建缓存路径下长期稳定运行的实用小工具。