Python pathlib.Path.walk 怎么做目录清理：剪枝、错误回调与版本边界

备份文件夹清理脚本通常不是难在“找到所有文件”，而是难在不该进入的目录要及时停下，权限异常要留下记录，统计结果还得能复核。Python 3.12 新增的 pathlib.Path.walk() 正好把这几个控制点放在一次遍历里：每轮拿到当前目录、子目录名列表和文件名列表，必要时直接修改子目录列表来剪枝。

先把目录清理任务拆成三个可核对的结果

假设应用把上传文件放在 /srv/uploads，临时目录是 cache，每天要统计超过 30 天的归档文件，并跳过缓存目录。一个看似简单的“遍历加删除”脚本，至少要回答三个问题：

• 当前正在看哪个目录，目录下面还有哪些分支？
• 哪些分支应该继续深入，哪些分支必须在入口处跳过？
• 某个目录没有权限时，是确实没有文件，还是扫描没有完成？

Path.rglob('*.log') 适合快速找匹配文件，但它不提供修改目录队列的入口。Path.walk() 更像一个带控制杆的文件夹扫描器，适合清理、审计、按目录统计这类需要“看一层再决定下一层”的任务。

Path.walk 返回什么，top_down 为什么重要

官方接口的基本形态是：

from pathlib import Path

for dirpath, dirnames, filenames in Path("/srv/uploads").walk():
    print(dirpath)
    print(dirnames)
    print(filenames)

每一轮的 dirpath 是当前目录的 Path 对象，dirnames 是子目录名列表，filenames 是当前目录下的非目录项名称。它们是名称，不是已经拼好的完整路径，真正访问文件时要使用 dirpath / filename。

默认的 top_down=True 意味着父目录先于子目录产出。这个顺序让剪枝成为可能：

root = Path("/srv/uploads")

for dirpath, dirnames, filenames in root.walk(top_down=True):
    dirnames[:] = [name for name in dirnames if name not in {"cache", ".snapshot"}]
    for filename in filenames:
        path = dirpath / filename
        print(path)

这里要注意是 dirnames[:] 原地替换。若只是给变量重新赋值，遍历器仍可能拿着原来的列表，剪枝就失效了。目录名过滤也应该尽量发生在入口处，而不是进入目录后再判断。

把清理动作放在遍历之后，先做一轮可回滚统计

生产脚本不建议拿到路径就删除。先把候选项、跳过项和失败项分别计数，跑一轮只读模式，确认结果与文件夹容量监控相符，再打开清理动作。

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

def collect_old_files(root: Path, days: int = 30):
    cutoff = datetime.now(timezone.utc).timestamp() - days * 86400
    candidates = []
    skipped = 0
    failures = []

    def record_error(error: OSError):
        failures.append({"path": str(error.filename), "error": str(error)})

    for dirpath, dirnames, filenames in root.walk(
        top_down=True,
        on_error=record_error,
        follow_symlinks=False,
    ):
        dirnames[:] = [name for name in dirnames if name not in {"cache", ".snapshot"}]
        skipped += len(filenames) - sum(1 for name in filenames if name.endswith(".tar.gz"))
        for filename in filenames:
            if not filename.endswith(".tar.gz"):
                continue
            path = dirpath / filename
            try:
                if path.stat().st_mtime 

这段代码只收集候选路径，不做删除。stat() 仍可能因为文件在扫描后被移动、权限变化或挂载短暂异常而失败，所以单独捕获文件级错误很有必要。目录级错误则交给 on_error，这样最终报告可以区分“扫描完成但没有命中”和“有一段目录没扫到”。

on_error、符号链接和版本兼容边界

follow_symlinks 默认是 False。目录符号链接不被当作普通子目录深入，这通常是清理任务更稳妥的默认值。若业务确实需要跟随链接，应在代码中增加已访问路径或设备边界的保护，而不是只把参数改成 True。

另外，Path.walk() 是 Python 3.12 的能力。部署环境如果仍有 3.11，比较稳的做法是把遍历封装成小函数：新环境使用 Path.walk，旧环境使用 os.walk，上层只接收统一的 Path 对象。这样迁移时不必改清理规则。

一次只读验收应该看哪些数字

正式启用删除前，建议把扫描结果写成一份短报告：

• 访问过的目录数，以及被剪枝的目录数。
• 发现的归档候选数、总字节数和最早修改时间。
• 跳过的非目标文件数，以及权限、断链等失败项。
• 同一份根目录重复运行时，结果是否稳定。

如果第二次运行仍然报告大量相同候选，但第一次并未执行删除，说明统计逻辑还没有问题；如果目录数突然下降，先核对是否把 dirnames 过滤条件写得过宽。不要用“脚本没有抛异常”替代结果验收，默认忽略错误时尤其如此。

常见问题

Path.walk 和 os.walk 应该选哪个？

Python 3.12 及以上、代码已经以 Path 为主时，Path.walk 更顺手；需要兼容旧版本或已有大量元组式处理代码时，继续用 os.walk 更省迁移成本。

为什么修改 dirnames 要用切片赋值？

遍历器需要看到原列表的变化。使用 dirnames[:] = ... 是原地修改，才能让后续遍历跳过被移除的目录；单纯写成 dirnames = ... 不会改变遍历队列。

on_error 不写会怎样？

默认情况下，扫描文件系统时发生的部分 OSError 会被忽略。这个行为适合“尽可能列出结果”的轻量查询，但不适合把扫描结果当作完整清理清单，审计和删除任务应该提供错误回调。

Path.walk 会自动递归目录符号链接吗？

不会，follow_symlinks 默认是 False。只有明确开启后才会跟随目录链接；开启前要额外评估循环链接、重复统计和跨挂载点访问。

把遍历能力变成可审计的清理步骤

Path.walk() 的价值不只是少写几行路径拼接代码，而是把“进入哪里、跳过什么、错误怎么留下证据”放到了同一个控制面上。先用 top_down=True 做剪枝，再用 on_error 区分缺失结果，最后把候选清单和统计数字保存下来，文件夹清理才有机会从一次性脚本变成可以放心重复运行的维护任务。