Python pathlib.Path.walk 怎么筛选目录：follow_symlinks、剪枝与路径类型核对

处理备份目录、构建产物或上传文件时，遍历逻辑经常先写成 os.walk()，后面又不断补 Path 转换。Python 的 pathlib.Path.walk() 把目录路径、子目录名和文件名放在同一个结果里，适合在遍历阶段完成筛选，再继续用 Path 做后续检查。

Path.walk() 默认不跟随符号链接；真正需要“筛选目录”时，关键不是过滤返回结果，而是在 top_down=True 时直接修改 dirnames，让不需要的目录根本不再向下走。

先把一个目录树的基线跑出来

假设项目目录里有 .git、build、cache 和 src。目标是只统计 Python 文件，并跳过构建产物与缓存。Path.walk() 的每一项是目录路径、子目录名列表和文件名列表，子目录名与文件名仍是字符串，拼接时要回到当前的 Path。

from pathlib import Path

root = Path("project")
for dirpath, dirnames, filenames in root.walk():
    dirnames[:] = [name for name in dirnames if name not in {".git", "build", "cache"}]
    for name in filenames:
        path = dirpath / name
        if path.suffix == ".py" and path.is_file():
            print(path)

这里的基线有两个检查点：一是 dirnames[:] = ... 原地修改列表，二是用 path.is_file() 排除同名目录。别把 dirnames = ... 写成普通赋值，那只会改变局部变量，不会改变遍历器下一步要进入的目录。

剪枝为什么比遍历后再过滤更合适

当目录中有很深的依赖缓存时，遍历后再丢弃结果已经晚了：扫描、系统调用和异常处理都发生过。top_down=True 是默认值，父目录先产出，程序可以修改 dirnames，随后遍历器只进入留下来的目录。

筛选规则最好集中在一个小函数里，避免把隐藏文件夹、缓存文件夹和输出文件夹的判断逻辑散落在多个循环分支中：

SKIP_DIRS = {".git", ".venv", "__pycache__", "dist"}

def iter_python_files(root: Path):
    for dirpath, dirnames, filenames in root.walk(top_down=True):
        dirnames[:] = sorted(name for name in dirnames if name not in SKIP_DIRS)
        for name in filenames:
            path = dirpath / name
            if path.suffix.lower() == ".py" and path.is_file():
                yield path

如果只想处理某个目录层级，也可以在剪枝函数里结合 dirpath.relative_to(root) 判断深度。不要为了“看起来更快”直接打开符号链接跟随，速度与遍历范围是两件事。

follow_symlinks 开不开，先看目录来源

默认 follow_symlinks=False。这时指向目录的符号链接不会被当作要进入的子目录，而会出现在文件名列表里。对用户上传目录、解压目录和构建工作区，默认值更容易控制范围。

开启后，链接目标会进入 dirnames。如果某个链接指向父目录，遍历可能反复绕圈；Path.walk() 不会自动记住已经访问过的目录。因此，只有在链接关系可控、并且确实要扫描链接目标时才传入 follow_symlinks=True。

for dirpath, dirnames, filenames in root.walk(follow_symlinks=False):
    for name in filenames:
        path = dirpath / name
        if path.is_symlink():
            print("skip link:", path)

一次小实验核对遍历结果，而不是凭感觉判断

可以在临时文件夹里造一个普通文件夹、一个链接文件夹和一个待剪枝文件夹，分别统计进入的文件夹数量与收集到的文件数量。测试的重点不是某台机器的绝对耗时，而是确认筛选规则不会越过边界。

from pathlib import Path

def collect(root: Path, follow: bool):
    visited = []
    files = []
    for dirpath, dirnames, filenames in root.walk(follow_symlinks=follow):
        visited.append(dirpath)
        files.extend(dirpath / name for name in filenames)
    return visited, files

visited, files = collect(Path("sample-tree"), follow=False)
assert all(path.name != "cache" for path in visited)
print(len(visited), len(files))

真实项目里，建议把“访问文件夹数、跳过文件夹数、链接数量、异常数量”作为简单指标记录下来。遇到扫描结果突然变少时，先看这些计数，再决定是规则变化、权限问题还是文件夹结构变了。

版本与路径类型的几个边界

• Path.walk() 是较新的 pathlib API，部署环境若仍有旧版 Python，要先在目标解释器中确认属性是否存在。
• dirnames 和 filenames 的元素是字符串，不要直接调用它们的 suffix 或 is_file；应先拼成 Path。
• 默认不跟随链接并不等于完成了安全校验；打开文件前仍应检查最终路径、权限和业务允许的根文件夹。
• on_error 默认忽略扫描异常。需要审计时传入处理函数，把异常路径和原因写入日志，避免把权限问题误判成“没有文件”。

相关问题

Path.walk 和 os.walk 该怎么选？

如果后续逻辑已经大量使用 Path，Path.walk() 可以减少路径对象转换；老项目若依赖 os.walk() 的既有工具链，也可以继续使用，重点是明确符号链接和剪枝规则。

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

遍历器持有原列表的引用。用 dirnames[:] 替换内容，才能影响它下一步的进入范围；重新绑定变量不会改变遍历器手中的列表。

开启 follow_symlinks 后如何防止循环？

优先不打开该选项；若业务必须打开，应限制根文件夹、记录已解析的文件夹身份，并为最大访问数量设置上限。不要把“遍历结束”当成链接结构一定无环的证明。

把筛选规则留在遍历入口

Path.walk() 最有价值的地方是让目录边界在入口处变得可见：先剪枝，再拼接路径，再核对文件类型，最后处理异常与统计。这样做出的扫描器更容易测试，也更容易解释为什么没有进入某个目录。