PHP递归遍历目录方法详解

本文深入剖析了PHP中两种主流目录递归遍历方式——原生scandir手动递归与RecursiveIterator封装迭代器——的核心差异与实战陷阱：scandir虽性能略优但极易因未过滤'.', '..'、路径拼接不规范或缺失权限校验而引发无限递归、Permission denied警告或路径判断失效；而RecursiveIterator自动规避点文件、路径安全，却默认静默跳过不可读目录且状态敏感，需谨慎配置选项与遍历模式。无论选择哪种方案，都必须直面权限校验、路径标准化和边界控制等关键问题，才能写出健壮、可维护的目录遍历代码。

scandir 递归遍历目录时容易漏掉子目录或报错

直接用 scandir 做递归，必须手动过滤 . 和 ..，否则会无限递归或跳进上级目录。PHP 7.4+ 虽然加了 SCANDIR_SORT_NONE 选项，但不影响路径逻辑——它只控制排序，不解决递归边界问题。

常见错误现象：Warning: scandir(): Failed to open dir: Permission denied 或遍历结果里混入 ./config 这种相对路径，导致 is_dir() 判断失败。

• 每次调用 scandir 后，用 array_diff($files, ['.', '..']) 清洗结果
• 拼接子路径时务必用 realpath($dir . DIRECTORY_SEPARATOR . $file) 或至少 $dir . '/' . $file（Windows 下 DIRECTORY_SEPARATOR 更稳妥）
• 在进入子目录前，先用 is_dir() + is_readable() 双重检查，避免权限错误中断流程

RecursiveIterator 实现更安全但要注意迭代器状态

RecursiveIterator 系列（比如 RecursiveDirectoryIterator + RecursiveIteratorIterator）本质是封装好的树形遍历器，不用手动处理 ./..，也不容易写错路径拼接。但它默认跳过不可读目录——不是报错，而是静默忽略，这点容易被当成“没遍历到”。

使用场景：需要稳定遍历、支持过滤、或后续要对接 FilterIterator 做条件筛选（比如只取 .php 文件）。

• 构造 RecursiveDirectoryIterator 时传 FilesystemIterator::SKIP_DOTS，比默认行为更明确
• RecursiveIteratorIterator 的第二个参数决定遍历深度，RecursiveIteratorIterator::SELF_FIRST 是常用值；用 LEAVES_ONLY 会跳过目录本身，只返回文件
• 迭代过程中不能随意调用 getChildren() 并再次 foreach —— 它会破坏当前迭代器状态，导致跳过条目或 Invalid argument supplied for foreach()

性能差异：scandir 递归 vs RecursiveIterator

小目录（scandir 手动递归通常更快——因为没对象创建开销，且能按需跳过子目录。而 RecursiveIterator 在初始化时就会尝试读取所有层级的目录结构，遇到权限不足的目录会直接停止该分支，但前期仍做了不少无效探测。

兼容性影响：PHP 5.3+ 支持 RecursiveIterator，但某些旧环境（如部分共享主机）禁用了 RecursiveDirectoryIterator 的 glob:// 尝试逻辑，表现为无法进入某些符号链接目录。

• 如果只需要列出路径，不用元信息（修改时间、大小等），scandir + foreach 组合更轻量
• 若需获取文件 mtime、size 或做 isLink() 判断，RecursiveDirectoryIterator 返回的 SplFileInfo 对象更省事
• 注意 RecursiveIteratorIterator 默认不抛异常，要用 setFlags(RecursiveIteratorIterator::CATCH_GET_CHILD) 才能在子目录出错时继续主循环

实际用例中容易忽略的路径编码和符号链接处理

中文路径在 scandir 下可能返回乱码（尤其 Windows + GBK 环境），而 RecursiveDirectoryIterator 内部用 UTF-8 处理，表现更一致。但两者对符号链接都默认跟随——也就是说，is_dir() 返回 true 的可能是软链指向的目录，不是原始路径本身。

这会导致两个问题：一是遍历路径重复（软链指向已遍历过的目录），二是统计磁盘占用时误算。

• 用 lstat() 替代 stat() 或 is_dir() 来判断是否为符号链接，再决定是否跳过
• 记录已访问的 realpath()（非原始路径），防止软链循环引用
• PHP 8.0+ 可用 RecursiveDirectoryIterator::FOLLOW_SYMLINKS 构造参数控制是否跟随，之前版本只能靠 is_link() + 手动跳过

本篇关于《PHP递归遍历目录方法详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！