Python Path.walk 与 os.walk 返回目录数据有什么区别

Python 3.12 以后，目录遍历可以写成面向对象的 Path.walk()，也可以继续使用成熟的 os.walk()。它们都逐个返回 (dirpath, dirnames, filenames)，真正影响选择的不是“能不能遍历”，而是路径对象类型、符号链接的默认归类、错误回调命名以及项目要支持的 Python 版本。

新项目已经以 pathlib.Path 为主，并且运行环境不低于 Python 3.12，可以优先选 Path.walk()；需要兼容更老版本、依赖字符串路径或必须保持旧代码接口时，继续选 os.walk()。迁移时尤其要重写路径拼接和符号链接判断。

同一棵目录树，先看返回值类型

两种接口的三元组字段名称相同，但 dirpath 的类型不同。Path.walk() 返回当前目录的 Path 对象，子目录名和文件名仍然是当前目录下的纯名称字符串；os.walk() 返回字符串形式的目录路径，另外两项也是名称字符串。

from pathlib import Path
import os

root = Path("project")

# Path.walk 直接返回 Path，适合继续调用 Path 的方法。
for dirpath, dirnames, filenames in root.walk():
    for name in filenames:
        file_path = dirpath / name
        print(file_path.suffix, file_path)

# os.walk 返回字符串路径，拼接时沿用 os.path.join。
for dirpath, dirnames, filenames in os.walk(root):
    for name in filenames:
        file_path = os.path.join(dirpath, name)
        print(os.path.splitext(file_path)[1], file_path)

需要裁剪目录时，两个接口都改 dirnames

默认是自顶向下遍历时，当前轮次拿到的 dirnames 可以原地修改。删除其中的目录名，遍历器就不会继续进入该目录；排序则可以在文件系统返回顺序不稳定时固定访问顺序。底向上遍历时，子目录已经生成，修改列表不会再改变递归路径。

from pathlib import Path

root = Path("project")
for dirpath, dirnames, filenames in root.walk(top_down=True):
    # 原地删除缓存目录，避免继续递归进入它。
    dirnames[:] = sorted(name for name in dirnames if name != "__pycache__")
    for name in filenames:
        print(dirpath / name)

# 删除目录树时改用 bottom-up，让文件先于父目录被处理。
for dirpath, dirnames, filenames in root.walk(top_down=False):
    # 这里只演示顺序；生产删除前还要确认目标范围和权限。
    print("目录即将处理：", dirpath)

迁移到 os.walk() 时，逻辑仍然成立，只需要把参数改为 topdown=True，并把路径拼接改为 os.path.join(dirpath, name)。不要只做字符串替换：调用方如果期待 Path，还要决定是在循环入口处转换，还是继续保留字符串。

符号链接和错误回调决定迁移成本

默认不跟随目录符号链接时，两个接口的列表归类不同，这是最容易造成迁移后漏处理的地方：os.walk() 会把指向目录的符号链接放入 dirnames，而 Path.walk() 会把它放入 filenames。如果业务把 filenames 当作“普通文件”直接打开，切换到 Path.walk() 后必须先补充符号链接判断。

两者都能通过开启跟随链接进入目标目录，但目录树存在指向父目录的链接时可能无限递归，不能把 follow_symlinks=True 或 followlinks=True 当成通用修复。错误处理也要同步改名：Path.walk(on_error=...) 接收 OSError，os.walk(onerror=...) 使用旧参数名。

按项目约束选择接口

实际迁移可以按三个点逐项替换：先改 dirpath 的拼接方式，再改 onerror 参数名，最后为目录符号链接补一条明确的处理分支。这样比直接把 os.walk 替换成 Path.walk 更稳妥。

常见问题

Path.walk 可以替代所有 os.walk 代码吗？

不能直接替代。至少要检查 Python 版本、dirpath 类型、错误回调参数名，以及目录符号链接在列表中的位置。

为什么 Path.walk 的 filenames 里会出现目录链接？

这是它在默认不跟随符号链接时的定义：目录符号链接会按文件名放入 filenames，与 os.walk 的归类不同。

修改 dirnames 什么时候不会生效？

自顶向下遍历时可以用它剪枝；底向上遍历时，子目录已经生成，之后修改列表不会改变遍历路径。

两个接口返回的文件名是绝对路径吗？

不是。dirnames 和 filenames 都是当前目录下的名称，完整路径需要分别使用 dirpath / name 或 os.path.join(dirpath, name)。