Python pathlib.Path.walk 清理大型目录怎么控风险：遍历顺序、符号链接与失败记录

清理缓存目录时，最容易出问题的不是遍历本身，而是脚本把“看到的路径”直接当成“可以删除的路径”。Python 3.12 的 pathlib.Path.walk() 给了我们更清楚的目录树控制：先决定是否跟随符号链接，再选择自顶向下还是自底向上，最后把失败项和待确认项留下记录。

为什么大型目录清理不能只写一行删除代码

临时文件目录通常混着三类东西：可以直接清理的缓存、需要保留的锁文件，以及指向其他位置的符号链接。整棵树一次性递归删除，失败时很难回答“删到哪里了”，更难恢复一个被错误选中的路径。

Path.walk() 适合把这个过程拆成可检查的阶段。它在每一层给出 dirpath、dirnames 和 filenames；列表是否排序取决于文件系统，所以需要排序时要在脚本中明确写出。

先用 top_down 控制遍历范围

自顶向下遍历时，可以直接修改当前的 dirnames 列表来裁剪分支。下面的示例只处理名称以 .cache- 开头的目录，同时保留 keep 目录；它只输出计划，不产生删除动作。

from pathlib import Path

ROOT = Path("/srv/app/cache")

def plan(root: Path) -> list[Path]:
    planned: list[Path] = []
    for dirpath, dirnames, filenames in root.walk(
        top_down=True,
        follow_symlinks=False,
        on_error=lambda exc: print(f"walk-error: {exc.filename}: {exc}"),
    ):
        dirnames[:] = sorted(
            name for name in dirnames
            if name.startswith(".cache-") and name != "keep"
        )
        planned.extend(dirpath / name for name in sorted(filenames))
    return planned

for item in plan(ROOT):
    print(item)

这里的关键不是筛选条件本身，而是把范围缩小发生在递归之前。不要先遍历整棵目录，再靠字符串判断“这条路径看起来像缓存”；如果目录正在被替换，还要把业务侧的并发写入暂停或改到临时目录。

符号链接要单独处理，别让脚本扩大清理范围

官方文档规定，follow_symlinks=False 时，指向目录的符号链接会出现在文件名列表中，而不是进入目录列表。这个默认值很重要：如果改成 True，链接可能把遍历带到目录树之外，甚至形成循环。

def safe_entries(root: Path) -> list[Path]:
    entries: list[Path] = []
    for dirpath, dirnames, filenames in root.walk(
        top_down=True,
        follow_symlinks=False,
    ):
        dirnames[:] = sorted(
            name for name in dirnames
            if not (dirpath / name).is_symlink()
        )
        entries.extend(dirpath / name for name in sorted(filenames))
    return entries

for item in safe_entries(ROOT):
    if item.is_symlink():
        print(f"skip-link: {item}")

这段代码仍然需要结合权限、挂载点和目录替换来验收。is_symlink() 只说明当前条目是链接，不代表链接目标一定安全；清理动作前应再次检查根目录和相对路径，不能把 dry-run 生成的旧清单直接当成执行授权。

执行阶段为什么要改成自底向上

目录只有在内容处理完后才可能为空，所以真正执行清理时使用 top_down=False 更符合文件系统约束。示例把文件、链接和目录分开记录；遇到权限错误时继续收集，最后由调用方决定是否让任务失败。

from dataclasses import dataclass

@dataclass
class Failure:
    path: Path
    reason: str

def cleanup(root: Path) -> list[Failure]:
    failures: list[Failure] = []
    for dirpath, dirnames, filenames in root.walk(
        top_down=False,
        follow_symlinks=False,
        on_error=lambda exc: failures.append(
            Failure(Path(exc.filename), f"walk: {exc}")
        ),
    ):
        for name in sorted(filenames):
            item = dirpath / name
            if item.is_symlink() or item.is_file():
                try:
                    item.unlink()
                except OSError as exc:
                    failures.append(Failure(item, f"unlink: {exc}"))
        for name in sorted(dirnames):
            item = dirpath / name
            try:
                item.rmdir()
            except OSError as exc:
                failures.append(Failure(item, f"rmdir: {exc}"))
    return failures

示例故意没有在异常处重新抛出，因为批量清理更需要知道全部失败项。生产脚本可以根据失败数量、目录是否仍在使用、是否有锁文件等条件设置非零退出码，但不能把“扫描失败”误报成“清理完成”。

把 dry-run 和最终确认接成两个不同阶段

推荐把 dry-run 输出保存成带根目录和生成时间的记录，再由执行命令重新扫描并比较关键条件：根目录是否相同、条目数量是否变化、是否出现新符号链接。只要这些条件不一致，就回到计划阶段。

• 计划阶段只读取目录，不调用 unlink() 或 rmdir()。
• 执行阶段再次校验根目录必须是预期绝对路径，拒绝空路径和文件系统根目录。
• 成功记录删除数量，失败记录保留路径、操作和异常文本。
• 把失败清单交给人工或下一次维护窗口处理，不要在同一轮无限重试。

常见问题：Path.walk 清理脚本怎么验收

Python 3.11 能直接使用 Path.walk 吗？

不能把它当成 3.11 的标准库接口。Path.walk() 是 Python 3.12 新增的能力；旧版本需要继续使用 os.walk() 或升级运行环境，并在部署检查中明确版本下限。

为什么不建议打开 follow_symlinks？

打开后会沿着链接进入目标目录，可能扩大清理范围，也可能因为链接指回父目录而无限递归。清理缓存时通常应保持默认值，并把链接作为跳过或人工复核项。

什么时候应该用 top_down=False？

当目标是删除文件后再删除空目录时使用它。自底向上能保证子项先被处理；如果只是筛选目录、裁剪遍历范围，则用自顶向下。

on_error 默认行为为什么不够？

默认扫描错误会被忽略，调用方可能只看到部分结果。需要审计或运维闭环时，应传入回调，把异常路径和原因写入失败记录，必要时让任务以失败状态结束。

落地前的最小检查清单

先确认 Python 版本不低于 3.12，再用测试目录覆盖普通文件、空目录、无权限条目、指向外部位置的符号链接和目录被替换的情况。上线时保留 dry-run 结果、实际处理数量和失败明细，这三份证据比一个“命令执行成功”的退出码更有用。