Python os.fwalk 怎样用目录文件描述符遍历文件

Python 的 os.fwalk() 可以看成是带目录文件描述符的 os.walk()：每次迭代除了返回目录路径、子目录名和文件名，还会返回当前目录对应的 dirfd。如果你需要对当前目录中的文件调用支持 dir_fd 的接口，os.fwalk 能减少反复拼接绝对路径的工作。

官方文档：https://docs.python.org/3/library/os.html#os.fwalk

最小判断是：普通遍历只需要路径时继续用 os.walk；需要当前目录文件描述符时使用 os.fwalk，并且只在当前迭代内使用返回的 dirfd。如果要留到下一轮，先用 os.dup 复制。

先看 os.fwalk 多返回的 dirfd

os.walk 每轮通常解包三个值，而 os.fwalk 返回四元组：dirpath 是当前目录路径，dirnames 是子目录名列表，filenames 是当前目录中的文件名列表，第四个 dirfd 是指向当前目录的文件描述符。

import os

for dirpath, dirnames, filenames, dirfd in os.fwalk("data"):
    # dirfd 指向当前 dirpath，可供支持 dir_fd 的接口使用。
    print(dirpath, len(dirnames), len(filenames), dirfd)

这里的 dirfd 不是另一个路径字符串，而是操作系统层面的目录句柄。dir_fd 则是很多 os 函数的参数名，表示“把相对名称解释在这个目录描述符下”；两者名称相近，角色并不相同。

用 dirfd 做当前目录的相对操作

当接口支持 dir_fd 时，可以把当前目录中的文件名和 dirfd 一起传入。例如 os.stat(name, dir_fd=dirfd) 表示查看当前遍历目录下名为 name 的对象。这样做的重点不是让代码“看起来更短”，而是把文件名和它所属的目录上下文绑定起来。

import os

def collect_sizes(root: str):
    records = []
    for dirpath, dirnames, filenames, dirfd in os.fwalk(root):
        # 在当前迭代内使用 dirfd，避免把文件名误解到别的目录。
        for name in filenames:
            try:
                info = os.stat(name, dir_fd=dirfd, follow_symlinks=False)
            except OSError as exc:
                # 单个文件不可访问时保留路径和错误，继续处理同目录其他文件。
                records.append({"path": os.path.join(dirpath, name), "error": str(exc)})
                continue
            records.append({"path": os.path.join(dirpath, name), "size": info.st_size})
    return records

follow_symlinks=False 让这段示例读取链接本身的属性，而不是把它自动追到目标文件。是否需要跟随链接取决于业务语义，不能把默认值和所有场景的安全策略混为一谈。

处理符号链接与目录描述符生命周期

os.fwalk 默认不跟随符号链接，这一点和某些递归遍历代码的直觉不同。需要遍历链接目标时必须显式评估 follow_symlinks，同时考虑目录树是否可能出现环路或重复访问。

更容易被忽略的是 dirfd 的生命周期。Python 官方文档说明，fwalk 返回的文件描述符通常只保证在下一次迭代前有效。如果要在循环外或下一轮继续使用，应先复制：

import os

saved_dirfds = []
for dirpath, dirnames, filenames, dirfd in os.fwalk("data"):
    # 复制描述符后才能把它安全地交给后续逻辑。
    saved_dirfds.append((dirpath, os.dup(dirfd)))

for dirpath, saved_fd in saved_dirfds:
    try:
        # 这里只展示描述符被保存后的使用边界，不执行删除操作。
        print(dirpath, os.fstat(saved_fd).st_mode)
    finally:
        # 复制出来的文件描述符由调用方负责关闭，避免资源泄漏。
        os.close(saved_fd)

这个例子故意把“当前轮直接使用”和“复制后延长生命周期”分开。不要把 dirfd 当成永久句柄缓存；也不要因为示例用了 dir_fd 就把所有路径操作都改写成描述符版本。

把 os.fwalk 放回工程边界

如果业务只需要得到目录树中的路径，os.walk 更直观；如果需要在目录上下文中调用 os.stat、os.open 等支持 dir_fd 的接口，os.fwalk 才有明显价值。选型时先看下游接口是否真的接受 dir_fd，而不是只因为返回值更多就替换。

还要注意平台差异：文件描述符、dir_fd 支持和符号链接行为属于操作系统接口能力。生产代码应对 OSError 做边界处理，并把“目标不存在”“权限不足”和“链接策略不符”区分记录。

常见问题

os.fwalk 和 os.walk 最主要的区别是什么？

os.fwalk 每轮多返回一个当前目录的 dirfd，并支持以目录描述符为上下文的相对操作；如果不需要这个能力，os.walk 通常更简单。

dirfd 和 dir_fd 是同一个东西吗？

不是。dirfd 是 fwalk 返回的整数文件描述符，dir_fd 是其他 os 函数接收该描述符的关键字参数。

为什么不能直接把 dirfd 保存到下一轮？

因为 fwalk 返回的描述符只保证在下一次迭代前有效。需要跨迭代保存时调用 os.dup，并在用完后 os.close。

记住三个点：先区分四元组字段，再确认下游接口是否支持 dir_fd，最后把 dirfd 的生命周期控制在当前迭代或显式复制之后。这样 os.fwalk 才是有边界的目录遍历工具，而不是更复杂的 os.walk 替代品。