Python pathlib.Path.walk 怎样用 on_error 处理遍历异常

Path.walk() 遇到无法读取的目录时，默认不会把 OSError 直接抛到调用方，而是忽略这次目录扫描错误并继续处理能够访问的部分。想知道哪些目录失败，就传入一个只接收一个 OSError 参数的 on_error 回调；回调可以记录 error.filename，也可以针对错误类型决定继续遍历还是重新抛出。

最小改法是给 Path.walk(on_error=处理函数) 传入回调：可预期的 PermissionError 记录后返回，不能接受的错误直接 raise。这样既不会因为一个目录权限问题丢失全部结果，也不会把真实故障静默吞掉。

官方地址：https://docs.python.org/3/library/pathlib.html

本文只讲 on_error 和 OSError 的处理边界，不把目录过滤、符号链接跟随策略或通用异常体系混在一起。Path.walk() 是 Python 3.12 加入的方法，先确认运行环境满足这个版本要求。

Path.walk 默认为什么看不到异常

Path.walk() 会为目录树中的每个目录生成 (dirpath, dirnames, filenames) 三元组。获取目录内容时，底层需要扫描文件系统；如果扫描阶段遇到权限不足等 OSError，而调用方没有提供 on_error，文档定义的默认行为是忽略该错误。

这意味着“遍历没有报错”不等于“每个目录都成功读取”。默认策略适合只关心可访问文件的批处理，但不适合审计、备份清单或需要知道遗漏位置的任务。

用 on_error 接收 OSError

on_error 不是异常类型，也不是一个布尔开关，而是一个可调用对象。每次目录扫描产生 OSError 时，Path.walk() 会把这个异常对象交给回调。异常对象通常可以提供 filename，因此日志里应优先记录具体失败路径，而不是只写一条“遍历失败”。

from pathlib import Path


def report_walk_error(error: OSError) -> None:
    # filename 能指出发生扫描错误的目录；没有路径时再退回错误文本。
    failed_path = getattr(error, "filename", None) or ""
    print(f"无法读取目录：{failed_path}；原因：{error}")


for directory, subdirectories, files in Path("data").walk(
    on_error=report_walk_error
):
    # 这里只消费可访问目录，错误信息已经由回调集中处理。
    print(directory, len(subdirectories), len(files))

回调签名保持为一个参数即可。不要把 on_error 写成需要额外位置参数的普通函数，除非先用闭包或 functools.partial 把额外配置绑定好。

按错误类型选择继续还是停止

回调返回后，遍历可以继续；如果回调重新抛出异常，遍历就会停止。常见做法是把“可预期、可记录”的权限错误与“必须让上层感知”的其他错误分开处理。

from pathlib import Path


def handle_walk_error(error: OSError) -> None:
    # 先保存出错目录，避免 PermissionError 的路径信息被日志格式丢掉。
    failed_path = getattr(error, "filename", None) or ""

    if isinstance(error, PermissionError):
        # 权限不足属于可跳过目录：记录后返回，Path.walk 会继续其他分支。
        print(f"跳过无权限目录：{failed_path}")
        return

    # 其他错误不能假定安全可忽略，重新抛出交给调用方决定。
    raise error


for directory, subdirectories, files in Path("data").walk(
    on_error=handle_walk_error
):
    # 这里处理正常取得的目录项，不在循环里重复捕获扫描异常。
    for filename in files:
        print(directory / filename)

这里的关键是“回调返回代表继续，回调抛出代表停止”，而不是把所有 OSError 都转换成空结果。若业务要求失败即终止，可以直接把异常交给上层；若业务允许部分成功，则应把跳过的路径写入日志或结果摘要。

把异常处理收进可复用函数

如果多个任务都需要遍历目录，不要在每个业务循环里重复写回调。可以让函数返回正常目录项和失败路径，调用方再决定是否把“部分成功”视为可接受结果。

from pathlib import Path


def walk_files(root: Path) -> tuple[list[Path], list[Path]]:
    # 分离正常文件与失败目录，调用方可以明确处理部分成功。
    files: list[Path] = []
    failures: list[Path] = []

    def collect_error(error: OSError) -> None:
        # filename 可能为空，因此用 root 作为最后的可读兜底值。
        failures.append(Path(error.filename or root))

    for directory, _subdirectories, names in root.walk(on_error=collect_error):
        # 只把 Path.walk 正常返回的文件加入结果，失败目录由回调收集。
        files.extend(directory / name for name in names)

    return files, failures

这个写法把“扫描错误发生在哪里”和“业务是否继续”分成两层：遍历函数负责收集，调用方可以在失败目录不为空时输出告警、返回部分结果，或者根据任务类型抛出业务异常。

几个容易混淆的边界

还要注意，Path.walk() 的默认 follow_symlinks=False 与本文的异常处理是两个独立参数。不要为了修复一个权限错误，顺手改变符号链接策略；这会让遍历范围发生另一种变化。

常见问题

只想打印错误，不想中断遍历怎么办？ 在 on_error 回调中记录 error.filename 后正常返回即可。

为什么回调里重新 raise 后没有后续目录？ 重新抛出表示该错误不可接受，Path.walk() 会停止并把异常交给调用方。

filename 一定是字符串吗？ 它来自底层 OSError，可能为空；记录时应准备兜底文本或根路径。

Path.walk 和 os.walk 的 onerror 参数一样吗？ 两者都能处理遍历错误，但接口对象和默认符号链接分类不同，迁移时不要只替换函数名。