Python pathlib 批量清理临时文件：后缀、修改时间和目录边界这样校验

清理构建缓存、导出中间文件或上传临时包时，真正危险的往往不是删文件这一行代码，而是筛选条件多写了一个目录、时间单位弄错，或者把待删文件直接处理后才发现范围过大。Python 的 pathlib 可以把路径解析、后缀判断和修改时间检查放在同一条可复核的流程里。

先把清理范围说清楚：删什么，不删什么

假设任务目录是 /srv/report-job/work，里面有临时压缩包、处理中间片段和最终产物。清理规则可以整理成下面这张小表：

这里的“7 天”不是通用安全常数。批处理每晚运行的场景可以按自身保留策略调整；第一次上线建议把阈值设得更长，并且初期只生成待删清单不执行实际删除。

用 pathlib 固定目录边界，再筛选后缀和 mtime

核心函数先返回所有候选文件，而不是直接执行删除。这样筛选过程可以单独抽出来测试，删除动作也能被前置的清单确认环节挡住。

from __future__ import annotations

from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Iterable


def find_expired_files(
    root: Path,
    suffixes: Iterable[str],
    keep_for: timedelta,
) -> list[Path]:
    base = root.expanduser().resolve()
    allowed = {item.lower() for item in suffixes}
    deadline = datetime.now(timezone.utc) - keep_for
    result: list[Path] = []

    if not base.is_dir():
        raise NotADirectoryError(base)

    for item in base.rglob("*"):
        if not item.is_file() or item.is_symlink():
            continue
        resolved = item.resolve()
        try:
            resolved.relative_to(base)
        except ValueError:
            continue
        if item.suffix.lower() not in allowed:
            continue
        modified = datetime.fromtimestamp(item.stat().st_mtime, tz=timezone.utc)
        if modified 

rglob 会递归遍历子目录，item.is_symlink() 直接把符号链接挡在结果外。relative_to(base) 是第二道边界检查：就算工作目录里出现了指向外部的链接，也不会把外部路径带进最终候选结果。

把候选文件写成清单，确认环节不要省

清单的价值在于让「准备删除哪些文件」成为一个完全透明的可观测结果。生产环境的任务可以把它当作构建产物长期保存；本地脚本运行时至少打印出待删文件总数量、占用总大小和前几条预览路径。

def write_plan(paths: list[Path], plan_file: Path) -> None:
    plan_file.parent.mkdir(parents=True, exist_ok=True)
    lines = [str(path) for path in paths]
    plan_file.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
    print(f"待处理文件：{len(paths)}，清单：{plan_file}")
    for path in paths[:5]:
        print(f"  - {path}")


root = Path("/srv/report-job/work")
plan = root / "cleanup-plan.txt"
targets = find_expired_files(root, {".tmp", ".part"}, timedelta(days=7))
write_plan(targets, plan)

清单文件本身不应被再次纳入待删候选，所以规则里只允许匹配 .tmp 和 .part。如果脚本要自动调度运行，建议把「候选数量超过预设阈值」设为强制失败条件，比如单次待删文件超过 5000 个就直接中断流程，避免上游任务异常导致大面积误清理。

删除阶段只消费已确认清单

确认完清单再逐条读取内容，同时重新检查对应路径仍然位于预设根目录范围内。文件很可能在等待确认的时间段内被替换，所以删除前的轻量复查环节仍然有实际意义。

def remove_from_plan(root: Path, plan_file: Path) -> tuple[int, int]:
    base = root.expanduser().resolve()
    removed = 0
    skipped = 0

    for raw in plan_file.read_text(encoding="utf-8").splitlines():
        candidate = Path(raw.strip())
        if not candidate.is_absolute():
            skipped += 1
            continue
        try:
            candidate.resolve().relative_to(base)
        except ValueError:
            skipped += 1
            continue
        if candidate.is_symlink() or not candidate.is_file():
            skipped += 1
            continue
        if candidate.suffix.lower() not in {".tmp", ".part"}:
            skipped += 1
            continue
        candidate.unlink()
        removed += 1

    return removed, skipped

这段代码故意没有用「清空整个目录」的简化写法。它接收的是已经生成好的路径清单，并且在每个文件上再次验证类型、位置和后缀。如果删除中途中断，剩余的清单文件仍然完整保留，可以从失败的位置继续核对处理。

定时任务里要留的检查点

脚本放进 cron、CI 或自动化任务平台后，最容易被忽略的就是异常记录。建议至少留存下面四项关键信息：

• 根目录实际解析完成后的绝对路径。
• 候选文件数量、总字节数和清单文件的存储路径。
• 成功删除数量、跳过数量以及第一个出现异常的路径。
• 清理结束后再次统计 .tmp、.part 文件数量。

如果清理任务在容器中运行，还要提前确认挂载点和宿主机文件夹的对应关系。容器内的 /srv/report-job/work 可能映射到宿主机的另一个路径，日志里记录完整解析后的路径，比只写一句「清理完成」要实用得多。

常见问题：清理脚本的边界与回退

为什么不直接用 glob 加 unlink 一行写完？

简单 glob 写法适合临时一次性本地操作，但不适合长期跑的定时任务：它通常没有时间阈值、符号链接拦截和数量门禁这几层校验。先产出完整清单，能让绝大多数误删风险在真正执行删除前就暴露出来。

mtime 是文件创建时间吗？

不是。st_mtime 是内容最后修改时间，在不同文件系统和跨设备复制流程里的含义可能存在差异。如果业务要求是「上传后保留 7 天」，最好把时间字段写入数据库或者旁挂元数据，不要只依赖原生文件系统的时间属性。

清单确认后对应文件不存在怎么办？

把它标记为跳过项，不要当成成功删除记录。文件可能已经被其他并行的清理任务处理，也可能是多个同逻辑任务重试造成的资源竞争；分开统计不同状态的记录，能帮你判断后续要不要调整任务调度规则。

一份可复用的清理速查表

1. 解析根目录并确认它确实是预期的工作区。
2. 遍历所有子文件，跳过文件夹、符号链接和不在允许列表里的后缀。
3. 按 UTC 时间戳比较 mtime，生成排序后的绝对路径清单。
4. 检查待删数量和总大小，超过预设阈值就直接停止流程。
5. 确认清单内容后逐条复查路径合法性，再执行删除并记录所有跳过项。

这套流程的核心不是用到了某个冷门 API，而是把「筛选候选」和「执行删除」拆成了两个带独立检查点的阶段。针对临时目录、缓存目录和批处理工作区的不同场景，都可以按相同的思路替换后缀规则、年龄阈值和数量门禁参数。