PHP递归遍历目录文件：RecursiveDirectoryIterator与自定义实现

在开发文件同步、日志归档、自动化构建工具或资产扫描系统时，遍历一个未知深度的文件夹树是高频的基础操作。PHP 提供了两种截然不同的技术路线：一种是基于标准 PHP 库（SPL）的 RecursiveDirectoryIterator 配合 RecursiveIteratorIterator，通过面向对象与流式迭代器实现；另一种是基于传统系统调用函数（如 scandir 或 opendir / readdir）配合用户自定义递归调用。

本文将围绕这两种实现方案展开深入剖析，拆解其工作原理、展示完整且可直接落地的代码范式，并从内存控制、执行效率、可维护性等维度横向对比，帮助读者根据工程实际情况做出最合理的架构选型。

一、核心机制：树形目录与深度优先遍历

操作系统中的目录结构在数据结构中表现为典型的多叉树（N-ary Tree）。根目录对应树的根节点，子目录是具有子节点的中间分支节点，而普通文件则是没有子节点的叶子节点。无论采用哪种编码方式，遍历目录的本质就是执行一次**深度优先搜索（DFS）**。

在递归扫描过程中，有两个必须严格处理的核心边界问题：

1. 特殊伪目录点号：所有的 POSIX 兼容文件系统以及 Windows 文件系统中，每个目录下都包含指向自身的 . 和指向父目录的 ..。如果递归逻辑未能严格跳过这两个虚拟项，程序将陷入死循环，直到触发 PHP 内存溢出或最大执行时间限制。
2. 符号链接（Symlinks）环路：当目录内部存在指向自身祖先路径的软链接时，深度优先遍历可能发生循环引用，必须具备防环机制或通过标志位显式控制是否穿透链接。

二、方案一：基于 SPL 标准库的优雅实现

PHP 5.3 以后，标准 PHP 库（SPL）成为了官方推荐的基础设施。在遍历多级目录时，SPL 提供了两个职责分离但紧密配合的类：

• RecursiveDirectoryIterator：继承自 FilesystemIterator，专门负责读取当前目录下的文件与子目录信息。当遇到子目录时，它能产生该子目录的新迭代器。
• RecursiveIteratorIterator：外层包装器，它负责将树状嵌套的多层迭代器“扁平化”，以线性的方式向外部循环输出元素。

1. 关键配置与构造标志

在实例化 RecursiveDirectoryIterator 时，推荐显式传递 FilesystemIterator::SKIP_DOTS 标志，底层 C 扩展会在扫描时直接过滤掉 . 和 ..，不仅提升效率，还避免了上层业务的冗余判断。

而在构造 RecursiveIteratorIterator 时，第二个参数 $mode 决定了遍历的具体策略：

• RecursiveIteratorIterator::LEAVES_ONLY（默认）：仅输出叶子节点，即只输出文件，不单独输出中间目录项。
• RecursiveIteratorIterator::SELF_FIRST：优先输出自身目录，然后再输出其内部的子项（适合需要先创建目标目录的复制操作）。
• RecursiveIteratorIterator::CHILD_FIRST：先输出子项，最后输出父目录（适合递归删除目录的场景）。

2. 生产级 SPL 遍历代码范式

以下示例封装了一个通用的文件扫描器，支持指定扩展名过滤与深度限制：

/**
 * 使用 SPL 递归遍历目录并获取所有文件
 *
 * @param string $rootPath 根目录路径
 * @param array $extensions 允许的文件后缀（如 ['php', 'sql']），空数组表示不过滤
 * @return Generator 返回 SplFileInfo 生成器，保持极低内存占用
 */
function getFilesViaSpl(string $rootPath, array $extensions = []): Generator
{
    if (!is_dir($rootPath) || !is_readable($rootPath)) {
        throw new InvalidArgumentException("目标目录不存在或无读取权限: {$rootPath}");
    }

    // 1. 实例化目录迭代器，显式跳过 . 和 .. 项
    $dirIterator = new RecursiveDirectoryIterator(
        $rootPath,
        FilesystemIterator::SKIP_DOTS | FilesystemIterator::KEY_AS_PATHNAME
    );

    // 2. 使用扁平化迭代器包装，指定仅输出叶子节点（文件）
    $flattenIterator = new RecursiveIteratorIterator(
        $dirIterator,
        RecursiveIteratorIterator::LEAVES_ONLY
    );

    // 3. 流式生成匹配的文件对象
    foreach ($flattenIterator as $path => $fileInfo) {
        /** @var SplFileInfo $fileInfo */
        if (!$fileInfo->isFile()) {
            continue;
        }

        if (!empty($extensions)) {
            $ext = strtolower($fileInfo->getExtension());
            if (!in_array($ext, $extensions, true)) {
                continue;
            }
        }

        yield $path => $fileInfo;
    }
}

// 执行示例
$targetDir = __DIR__ . '/src';
foreach (getFilesViaSpl($targetDir, ['php']) as $filePath => $info) {
    echo "找到文件: " . $info->getFilename() . " | 大小: " . $info->getSize() . " 字节\n";
}

三、方案二：自定义递归函数的经典实现

自定义递归是理解算法逻辑的最佳途径。它主要依赖传统的文件系统函数，常见的有 scandir() 或 opendir() / readdir() / closedir()。

在设计自定义递归函数时，必须建立清晰的状态隔离。函数应接收当前路径，并在读取内部元素时，通过判断 is_dir() 决定是将结果继续压入调用栈递归，还是直接放入当前收集器中。

1. 健壮的自定义递归实现范式

自定义实现常见的一个缺陷是路径拼接随意，容易在不同操作系统（如 Windows 与 Linux）下出现混合斜杠问题。应当始终使用 DIRECTORY_SEPARATOR 常量或在入口处统一规范化处理：

/**
 * 自定义递归函数遍历目录
 *
 * @param string $dir 目标扫描目录
 * @param array &$results 结果收集引用
 * @return array 扁平化的文件绝对路径列表
 */
function scanDirectoryCustom(string $dir, array &$results = []): array
{
    $dir = rtrim($dir, DIRECTORY_SEPARATOR);
    
    if (!is_dir($dir) || !is_readable($dir)) {
        return $results;
    }

    // 使用 scandir 读取当前层级所有实体（包含隐蔽文件与点号）
    $items = scandir($dir);
    if ($items === false) {
        return $results;
    }

    foreach ($items as $item) {
        // 核心防线：必须严格跳过当前目录 . 和上级目录 ..
        if ($item === '.' || $item === '..') {
            continue;
        }

        $fullPath = $dir . DIRECTORY_SEPARATOR . $item;

        // 遇子目录递归调用，遇普通文件直接追加
        if (is_dir($fullPath)) {
            // 排除软链接可能带来的循环递归风险
            if (!is_link($fullPath)) {
                scanDirectoryCustom($fullPath, $results);
            }
        } else {
            $results[] = $fullPath;
        }
    }

    return $results;
}

// 执行示例
$allFiles = scanDirectoryCustom('/var/www/html/project');
echo "共计检索到 " . count($allFiles) . " 个文件\n";

四、关键差异对比与架构选型依据

在同等运行环境下（如 PHP 8.2+、遍历包含 5 万个文件及 8 级嵌套目录的真实工程），两种方案在内存消耗、代码扩展度与容错表现上呈现出显著的差异：

五、工程级避坑与最佳实践

1. 权限防护：无论是 SPL 还是自定义递归，扫描至无权访问的目录时都会触发 UnexpectedValueException（SPL）或返回 false。生产环境中必须对不可读路径做好防御性捕获，避免整个进程异常中断。
2. 符号链接陷阱：如果项目包含软链接，SPL 默认不会追踪（除非主动传入 FilesystemIterator::FOLLOW_SYMLINKS）。开启追踪时务必警惕死循环，建议使用哈希表或 realpath() 记录已经访问过的 inode 节点号。
3. 大目录处理与及时刷盘：处理几十万量级的文件归档时，切忌将结果聚合到一个大的 PHP 数组中。应严格遵循 SPL 流式迭代器模式，边遍历边写入文件或消息队列。

六、结论

PHP 递归遍历目录并不是一道单一答案的选择题。在工程化、标准化要求高、或者目录规模不可预测的现代 PHP 框架与类库开发中，SPL 的 RecursiveDirectoryIterator 搭配生成器是无可争议的首选，它不仅具备高执行效率和出色的内存安全边界，还完美融合了面向对象的现代语法生态。

而在轻量级脚本、自动化运维单文件工具或需要对遍历项实施即时非线性过滤与排序的特殊场景下，自定义递归函数依然凭借其极高的透明度与自由度保有独特的应用价值。掌握两者的底层逻辑与边界限制，能够在处理各种复杂的底层文件操作时游刃有余。