Python os.scandir 怎样减少目录遍历中的属性查询

我最近整理一个目录扫描小工具时，先写了最直观的版本：用 os.listdir() 得到文件名，再对每个路径调用 os.stat()。代码当然能工作，但类型判断和属性读取被拆成了两次操作，后面还要自己处理路径拼接和资源边界。对这类任务，os.scandir() 更合适：它返回带有文件名、路径和类型方法的 DirEntry，很多类型判断可以直接利用目录枚举时拿到的信息。

实用结论是：只判断文件类型时优先用 entry.is_file() 或 entry.is_dir()；确实需要大小、时间等完整属性时，再对同一个条目调用一次 entry.stat()。如果目录内容可能已经变化，不能把条目上的缓存当成永久真相。

官方地址：https://docs.python.org/3/library/os.html#os.scandir

先做一个可复用的目录扫描小工具

我会先把需求收窄成一个小项目：输入目录，返回普通文件的名称和大小。这个边界足够展示 scandir 的价值，也不会把文章混成通用目录索引设计。下面的示例只使用 Python 标准库，保存为 scandir_demo.py 即可继续改造成自己的工具。

import os


def collect_files(root):
    # 让调用方传入目录路径，结果只保留普通文件。
    files = []
    with os.scandir(root) as entries:
        for entry in entries:
            # 不跟随符号链接，避免把链接目标误当成普通文件。
            if not entry.is_file(follow_symlinks=False):
                continue
            # 需要文件大小时才读取 stat，并复用这一次结果。
            info = entry.stat(follow_symlinks=False)
            files.append((entry.name, info.st_size))
    # 排序让上层展示顺序稳定，但不代表目录的原始顺序。
    return sorted(files, key=lambda item: item[0])


if __name__ == '__main__':
    # 这是示例入口；实际项目可改成 argparse 参数。
    for name, size in collect_files('data'):
        print(f'{name}: {size} bytes')

这里有两个容易被忽略的点。第一，with os.scandir(root) 会在离开代码块时关闭迭代器，目录很多或中途抛异常时也不容易遗留资源。第二，is_file(follow_symlinks=False) 和 stat(follow_symlinks=False) 采用同一套符号链接口径，返回结果更容易解释。

命令行入口可以这样写：

# 运行示例目录扫描工具，目录不存在时会抛出对应的 OSError。
python3 scandir_demo.py

为什么减少的是额外查询，而不是所有 stat

os.scandir() 的优势不应被理解成“以后完全不需要系统调用”。目录项通常已经携带了文件类型信息，因此对普通非符号链接调用 is_file() 或 is_dir() 时，很多平台不必再次查询；但 entry.stat() 仍然是读取大小、时间等完整属性的入口，在 Unix 上通常需要系统调用。

如果我只是统计文件数量，会停在 is_file()；如果还要生成清单，才读取 st_size。这种按需求取属性的写法比把每个目录项都无条件 stat 一遍更清楚。至于实际速度，文件系统、网络挂载、符号链接比例和目录规模都会影响结果，不能拿一个环境的倍数当成普遍承诺。

把缓存和符号链接边界写进代码

DirEntry 会缓存部分方法结果，而且 follow_symlinks=True 与 False 使用分开的缓存。这个设计很方便，但也意味着同一个条目不是一个永远新鲜的数据库记录。下面的函数把“枚举时的判断”和“重新读取”分成两个明确出口。

import os


def inspect_entry(entry):
    # 两种 follow_symlinks 取值分别表达不同的业务口径。
    link_is_file = entry.is_file(follow_symlinks=True)
    physical_is_file = entry.is_file(follow_symlinks=False)
    # 条目可能已被外部进程修改；这里显式获取当前路径属性。
    fresh_info = os.stat(entry.path, follow_symlinks=False)
    return {
        'name': entry.name,
        'path': entry.path,
        'link_is_file': link_is_file,
        'physical_is_file': physical_is_file,
        'fresh_size': fresh_info.st_size,
    }


def inspect_directory(root):
    # 迭代器只在本次函数调用中使用，不把 DirEntry 长期保存。
    with os.scandir(root) as entries:
        return [inspect_entry(entry) for entry in entries]

这里特意用 os.stat(entry.path, follow_symlinks=False) 作为“新鲜属性”出口，而不是继续依赖 DirEntry.stat() 的旧缓存。若业务允许使用枚举时的快照，则可以继续复用 entry.stat()；若目录会被其他进程修改，应该在真正需要判断的时点重新读取，并准备好处理 FileNotFoundError 或 PermissionError。

我最后保留的实践清单

这次改造后，我会按下面的条件选择写法：

• 只做类型筛选：使用 is_file()、is_dir()，并明确是否跟随符号链接。
• 需要大小或时间：对同一条目读取一次 stat()，不要在多个函数里重复取。
• 需要最新结果：用 os.stat(entry.path) 重新读取，不把缓存当成实时状态。
• 目录可能很大或中途失败：用 with os.scandir() 管理迭代器，并捕获业务允许处理的 OSError。
• 需要跨函数传递：传递 entry.name 或 entry.path，不要长期保存 DirEntry 对象。

常见问题

os.scandir() 会递归遍历所有子目录吗？

不会。它只枚举传入目录的一层；递归需要自己组合目录队列或调用其他标准库工具，文章中的示例没有把递归语义混进来。

为什么同一个条目要区分 follow_symlinks？

跟随符号链接时判断的是目标，不跟随时判断的是链接本身。两者服务于不同的安全和业务口径，不能只改一个参数却沿用另一种解释。

DirEntry 可以放进全局缓存吗？

不建议。官方文档明确提醒条目不适合长期保存；目录内容变化后，缓存的类型和属性可能不再代表当前状态。长期缓存更适合保存路径和业务需要的快照字段。

我对这个小工具的最终取舍是：用 scandir 负责一次目录枚举，用 DirEntry 负责就地判断，用显式的 stat 决定何时读取属性。这样既能减少不必要的查询，也不会把“缓存存在”误写成“数据永远最新”。