当前位置：首页 > news >正文

python遍历目录os.walk()

news 2026/7/30 17:48:00

os.walk()是 Python 标准库os模块中用于遍历目录树的核心函数。它通过生成器（Generator）的方式，递归地访问指定路径下的所有子目录和文件，是处理文件系统批量操作（如搜索、统计、重命名、删除等）最高效且常用的工具之一。

以下从工作原理、参数详解、返回值结构、典型应用场景及注意事项五个方面进行详细解释。

1. 核心工作原理

os.walk()的本质是一个‌目录树遍历生成器‌。

‌递归遍历‌：它会自动深入每一个子目录，直到遍历完整个目录树。
‌内存友好‌：作为生成器，它不会一次性将所有文件路径加载到内存中，而是“按需”逐层 yield 数据。这使得它在处理包含数十万甚至上百万文件的超大目录时，依然能保持极低的内存占用。
‌遍历顺序‌：支持“自上而下”（Top-down）和“自下而上”（Bottom-up）两种遍历策略。

2. 函数签名与参数详解

函数原型如下：

os.walk(top, topdown=True, onerror=None, followlinks=False)

参数	类型	默认值	说明
‌top‌	str/path-like	必传	需要遍历的根目录路径。
‌topdown‌	bool	`True`	‌遍历方向‌。 -`True`：先处理当前目录，再处理子目录（自上而下）。 -`False`：先处理最深层的子目录，最后回溯到根目录（自下而上/后序遍历）。注：若需修改`dirs`列表以跳过某些子目录，必须使用默认的`True`。
‌onerror‌	callable	`None`	‌错误处理函数‌。当遍历过程中遇到权限不足或目录不存在等错误时，会调用此函数。该函数接收一个`OSError`实例作为参数。若未指定，错误会被忽略或抛出异常终止遍历。
‌followlinks‌	bool	`False`	‌是否跟随符号链接‌。 -`True`：访问指向目录的软链接（Symbolic Links）。 -`False`：不跟随软链接。警告：若目录中存在循环引用的软链接，设置为`True`可能导致无限循环。

3. 返回值结构

os.walk()每次迭代会返回一个三元组(root, dirs, files)：

‌root‌ (str)：
- 当前正在遍历的目录的‌完整路径‌。
‌dirs‌ (list)：
- 当前目录下所有‌子目录的名称列表‌（不包含路径，仅文件名）。
- 重要特性：如果topdown=True，你可以就地修改这个列表（例如使用dirs.remove()或切片赋值），os.walk()将不会进入被移除的子目录。这是实现“跳过特定文件夹”的关键机制。
‌files‌ (list)：
- 当前目录下所有‌非目录文件的名称列表‌（不包含路径，仅文件名）。

‌注意‌：dirs和files中的名称都是相对当前root的basename，‌不是完整路径‌。获取文件完整路径时，必须使用os.path.join(root, name)进行拼接。

4. 典型应用场景与代码示例

场景一：基础遍历，打印所有文件路径

这是最常见的用法，用于查看目录结构或收集文件列表。

import os path = './project' # 替换为你的目标路径 for root, dirs, files in os.walk(path): for filename in files: # 必须使用 os.path.join 拼接完整路径，避免手动拼接斜杠导致的跨平台问题 file_path = os.path.join(root, filename) print(file_path)

场景二：按后缀名筛选文件（如查找所有 .py 文件）

结合字符串方法endswith()进行过滤。

import os def find_files_by_extension(root_dir, extension): py_files = [] for root, dirs, files in os.walk(root_dir): for file in files: if file.endswith(extension): py_files.append(os.path.join(root, file)) return py_files # 使用示例 python_files = find_files_by_extension('./src', '.py') print(python_files)

场景三：跳过特定目录（优化性能）

利用topdown=True时修改dirs列表的特性，跳过.git、node_modules或__pycache__等无需遍历的目录，显著提升遍历速度。

import os exclude_dirs = {'.git', 'node_modules', '__pycache__', 'venv'} for root, dirs, files in os.walk('./project'): # 原地修改 dirs 列表，移除需要排除的目录 # os.walk 在 topdown=True 时，会根据修改后的 dirs 决定下一步进入哪些子目录 dirs[:] = [d for d in dirs if d not in exclude_dirs] for file in files: print(os.path.join(root, file))

场景四：批量重命名或移动文件

结合shutil模块可以实现文件的批量处理。

import os import shutil source_dir = './old_logs' target_dir = './archived_logs' if not os.path.exists(target_dir): os.makedirs(target_dir) for root, dirs, files in os.walk(source_dir): for file in files: if file.endswith('.log'): src_path = os.path.join(root, file) dst_path = os.path.join(target_dir, file) # 简单示例：移动文件 shutil.move(src_path, dst_path) print(f"Moved: {src_path} -> {dst_path}")

5. 进阶注意事项与最佳实践

‌路径拼接安全‌：
- ‌错误做法‌：root + '/' + file或root + '\\' + file。这在 Windows 和 Linux 混用或路径末尾有无斜杠时容易出错。
- ‌正确做法‌：始终使用os.path.join(root, file)。Python 3.4+ 也可以使用pathlib.Path(root) / file。
‌避免在遍历中修改目录结构‌：
- 如果在遍历过程中删除或移动了当前正在遍历的目录或其父目录，可能会导致os.walk()行为不可预测或抛出异常。建议先收集所有路径，遍历结束后再统一执行删除或移动操作。
‌topdown的选择‌：
- 如果需要‌删除目录树‌，建议使用topdown=False。因为删除父目录前必须先删除其子内容，自下而上的遍历顺序天然符合这一逻辑。
- 如果需要‌剪枝（跳过子目录）‌，必须使用topdown=True。
‌符号链接风险‌：
- 除非明确知道目录结构中没有循环引用，否则不要随意设置followlinks=True，否则程序可能陷入死循环。
‌性能考量‌：
- os.walk()底层基于os.scandir()（Python 3.5+），比旧的os.listdir()效率更高，因为它能一次性获取文件属性而无需额外的系统调用。对于海量文件遍历，它是首选方案。