Java 遞歸遍歷目錄獲取所有文件路徑完整實現

Java 遞歸/迭代遍歷目錄樹：獲取所有文件絕對路徑的高性能實現與陷阱避坑

文件系統遍歷是批量處理、索引構建、備份同步、代碼掃描等場景的基礎操作。本文對比遞歸、迭代、NIO.2 三種方案，分析性能、記憶體、異常處理差異，提供生產就緒工具類。

方案對比速覽

方案一：迭代廣度優先 (BFS) - 生產環境首選

import java.io.File;
import java.io.IOException;
import java.util.*;

public final class FileScanner {
    private FileScanner() {}

    /**
     * 獲取目錄下所有文件絕對路徑 (廣度優先, 非遞歸)
     * @param rootDir 根目錄
     * @return 文件路徑列表 (不包含目錄)
     * @throws IOException 訪問異常
     */
    public static List listAllFiles(String rootDir) throws IOException {
        File root = new File(rootDir);
        if (!root.exists() || !root.isDirectory()) {
            throw new IllegalArgumentException("無效目錄: " + rootDir);
        }
        
        List result = new ArrayList<>();
        Queue dirQueue = new ArrayDeque<>();
        dirQueue.offer(root);
        
        while (!dirQueue.isEmpty()) {
            File currentDir = dirQueue.poll();
            File[] files = currentDir.listFiles();
            
            if (files == null) continue; // 權限不足或 IO 錯誤
            
            for (File file : files) {
                if (file.isDirectory()) {
                    dirQueue.offer(file);
                } else {
                    result.add(file.getAbsolutePath());
                }
            }
        }
        return result;
    }

    /**
     * 獲取文件路徑並寫入文件 (流式, 低記憶體)
     */
    public static void listFilesToFile(String rootDir, String outputFile) throws IOException {
        File root = new File(rootDir);
        try (var writer = new java.io.BufferedWriter(
                new java.io.OutputStreamWriter(
                    new java.io.FileOutputStream(outputFile), "UTF-8"))) {
            
            Queue queue = new ArrayDeque<>();
            queue.offer(root);
            
            while (!queue.isEmpty()) {
                File dir = queue.poll();
                File[] files = dir.listFiles();
                if (files == null) continue;
                
                for (File f : files) {
                    if (f.isDirectory()) {
                        queue.offer(f);
                    } else {
                        writer.write(f.getAbsolutePath());
                        writer.newLine();
                    }
                }
            }
        }
    }
}

方案二：NIO.2 Files.walk (Java 8+ 函數式風格)

import java.io.IOException;
import java.nio.file.*;
import java.util.List;
import java.util.stream.Collectors;

public class NioFileScanner {
    /**
     * 使用 Stream API 遍歷 (深度優先)
     * @param maxDepth 最大深度, -1 無限制
     */
    public static List walkFiles(String rootDir, int maxDepth) throws IOException {
        Path root = Paths.get(rootDir);
        try (var stream = Files.walk(root, maxDepth, FileVisitOption.FOLLOW_LINKS)) {
            return stream
                .filter(Files::isRegularFile)
                .map(Path::toAbsolutePath)
                .map(Path::toString)
                .collect(Collectors.toList());
        }
    }
    
    /**
     * 帶過濾條件的遍歷 (如: 只取 .java 文件, 排除 target 目錄)
     */
    public static List walkFiltered(String rootDir, String globPattern, String... excludeDirs) throws IOException {
        Path root = Paths.get(rootDir);
        Set excludeSet = new HashSet<>(Arrays.asList(excludeDirs));
        
        try (var stream = Files.walk(root, FileVisitOption.FOLLOW_LINKS)) {
            return stream
                .filter(p -> !excludeSet.stream().anyMatch(p::startsWith)) // 簡化排除邏輯
                .filter(Files::isRegularFile)
                .filter(p -> p.getFileName().toString().matches(globPattern.replace("*", ".*")))
                .map(Path::toAbsolutePath)
                .map(Path::toString)
                .collect(Collectors.toList());
        }
    }
    
    /**
     * 並行遍歷 (多核 CPU 加速, 大目錄顯著提速)
     */
    public static List walkParallel(String rootDir) throws IOException {
        return Files.walk(Paths.get(rootDir))
            .parallel()
            .filter(Files::isRegularFile)
            .map(Path::toAbsolutePath)
            .map(Path::toString)
            .collect(Collectors.toList());
    }
}

方案三：Files.walkFileTree 最大控制力 (Java 7+)

import java.io.IOException;
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.ArrayList;
import java.util.List;

public class WalkFileTreeScanner {
    public static List walkWithControl(String rootDir) throws IOException {
        List result = new ArrayList<>();
        Path root = Paths.get(rootDir);
        
        Files.walkFileTree(root, new SimpleFileVisitor() {
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
                if (attrs.isRegularFile()) {
                    result.add(file.toAbsolutePath().toString());
                }
                return FileVisitResult.CONTINUE;
            }
            
            @Override
            public FileVisitResult visitFileFailed(Path file, IOException exc) {
                // 記錄錯誤但繼續遍歷
                System.err.println("訪問失敗: " + file + " - " + exc.getMessage());
                return FileVisitResult.CONTINUE;
            }
            
            @Override
            public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
                // 可在此過濾跳過目錄 (如 .git, target, node_modules)
                String name = dir.getFileName().toString();
                if (name.equals(".git") || name.equals("target") || name.equals("node_modules")) {
                    return FileVisitResult.SKIP_SUBTREE;
                }
                return FileVisitResult.CONTINUE;
            }
        });
        
        return result;
    }
}

性能基準測試參考 (10萬文件, 5層深度, SSD)

生產環境關鍵注意事項

1. 權限處理：listFiles() 返回 null 表示無權限或 IO 錯誤，必須 null 判斷
2. 符號鏈接：FileVisitOption.FOLLOW_LINKS 可能導致循環遍歷，需維護已訪問 Set<Path> 去重
3. 大目錄記憶體：結果列表可能巨大，優先使用流式寫入文件或数据庫，避免全量載入內存
4. 異常隔離：單文件/目錄失敗不應中斷整個掃描，採用 visitFileFailed 或 try-catch 繼續
5. 編碼問題：文件名含特殊字符時，getAbsolutePath() 依賴系統編碼，跨平台建議用 Path.toString()
6. 性能調優：排除 .git、target、node_modules、.idea 等無關目錄可提速 50%+

工具類擴展建議

// 1. 文件過濾器鏈
public interface FileFilter {
    boolean accept(Path path, BasicFileAttributes attrs);
}

// 2. 進度回調
public interface ScanProgressListener {
    void onDirectoryScanned(Path dir, int fileCount);
    void onFileFound(Path file);
    void onError(Path path, IOException e);
}

// 3. 結果沉澱策略
public interface ResultSink {
    void accept(String absolutePath);
    void close();
}

// 實現: 寫文件、入庫、發送消息隊列、構建索引...