核心 API 概覽
| 方法 | 返回類型 | 範圍 | 支援通配符 | 備註 |
| Directory.GetFiles() | string[] | 僅指定目錄 | 是 | 最簡單、載入全量陣列 |
| Directory.GetDirectories() | string[] | 僅指定目錄 | 是 | 同上 |
| Directory.GetFileSystemEntries() | string[] | 檔案+子目錄 | 是 | 單次調用獲取兩者 |
| DirectoryInfo.GetFiles() | FileInfo[] | 僅指定目錄 | 是 | 含完整元數據(大小、時間、屬性) |
| DirectoryInfo.GetDirectories() | DirectoryInfo[] | 僅指定目錄 | 是 | 含元數據 |
| DirectoryInfo.EnumerateFiles() | IEnumerable<FileInfo> | 僅指定目錄 | 是 | 延遲執行、記憶體友善 |
| DirectoryInfo.EnumerateDirectories() | IEnumerable<DirectoryInfo> | 僅指定目錄 | 是 | 同上 |
| Directory.EnumerateFileSystemEntries() | IEnumerable<string> | 檔案+目錄 | 是 | .NET 4.0+ |
基本操作範例
獲取單層檔案與子目錄
string path = @"C:\Projects\MyApp";
// 簡單陣列版 (小目錄適用)
string[] files = Directory.GetFiles(path, "*.cs", SearchOption.TopDirectoryOnly);
string[] dirs = Directory.GetDirectories(path);
// 資訊豐富版
var dirInfo = new DirectoryInfo(path);
FileInfo[] fileInfos = dirInfo.GetFiles("*.cs");
DirectoryInfo[] subDirs = dirInfo.GetDirectories();
foreach (var f in fileInfos)
{
Console.WriteLine($"{f.Name,-30} {f.Length,12:N0} bytes {f.LastWriteTime:yyyy-MM-dd HH:mm} {(f.Attributes & FileAttributes.ReadOnly) != 0 ? "R" : ""}");
}
foreach (var d in subDirs)
{
Console.WriteLine($"[DIR] {d.Name,-30} {d.LastWriteTime:yyyy-MM-dd HH:mm}");
}
遞歸遍歷 (SearchOption.AllDirectories)
// 一行搞定 (但大目錄記憶體壓力大)
string[] allFiles = Directory.GetFiles(path, "*.*", SearchOption.AllDirectories);
// 進階:自定義遞歸 (可過濾、處理異常、進度回報)
public static IEnumerable EnumerateFilesRecursive(string rootPath, string pattern = "*.*",
Func directoryFilter = null, Action progress = null)
{
var rootDir = new DirectoryInfo(rootPath);
if (!rootDir.Exists) yield break;
var stack = new Stack();
stack.Push(rootDir);
while (stack.Count > 0)
{
var currentDir = stack.Pop();
// 目錄過濾
if (directoryFilter != null && !directoryFilter(currentDir)) continue;
// 列舉檔案 (延遲執行)
IEnumerable files;
try { files = currentDir.EnumerateFiles(pattern); }
catch (UnauthorizedAccessException) { continue; } // 跳過無權限目錄
catch (PathTooLongException) { continue; }
catch (DirectoryNotFoundException) { continue; }
foreach (var file in files)
{
yield return file;
progress?.Invoke(file.FullName);
}
// 壓入子目錄 (深度優先)
try
{
foreach (var subDir in currentDir.EnumerateDirectories())
{
stack.Push(subDir);
}
}
catch { /* 忽略無權限子目錄 */ }
}
}
// 使用
foreach (var file in EnumerateFilesRecursive(@"C:\Source", "*.cs",
d => !d.Name.StartsWith(".") && d.Name != "bin" && d.Name != "obj",
f => Console.WriteLine($"Processing: {f}")))
{
// 處理檔案...
}
廣度優先 vs 深度優先
// 廣度優先 (Queue) - 適合按層級處理、尋找最近路徑
public static IEnumerable BreadthFirst(DirectoryInfo root)
{
var queue = new Queue();
queue.Enqueue(root);
while (queue.Count > 0)
{
var dir = queue.Dequeue();
yield return dir;
foreach (var sub in dir.EnumerateDirectories()) queue.Enqueue(sub);
}
}
// 深度優先 (Stack/遞歸) - 適合完整遍歷、記憶體較省
public static IEnumerable DepthFirst(DirectoryInfo root)
{
var stack = new Stack();
stack.Push(root);
while (stack.Count > 0)
{
var dir = stack.Pop();
yield return dir;
foreach (var sub in dir.EnumerateDirectories()) stack.Push(sub);
}
}
高效能模式:Enumerate + LINQ + 平行處理
// .NET 6+ 現代寫法
var largeFiles = Directory.EnumerateFiles(root, "*.*", SearchOption.AllDirectories)
.AsParallel() // 平行處理
.Select(f => new FileInfo(f))
.Where(f => f.Length > 100_000_000) // > 100MB
.OrderByDescending(f => f.Length)
.Take(10)
.ToList();
// 記憶體受限環境:分批處理
public static async IAsyncEnumerable EnumerateFilesAsync(string path, string pattern)
{
var dir = new DirectoryInfo(path);
foreach (var file in dir.EnumerateFiles(pattern))
yield return file;
foreach (var subDir in dir.EnumerateDirectories())
{
await foreach (var file in EnumerateFilesAsync(subDir.FullName, pattern))
yield return file;
}
}
檔案資訊屬性速查
| 屬性 | 型別 | 說明 |
| Exists | bool | 檔案是否存在 |
| Name | string | 檔名含副檔名 |
| Extension | string | 副檔名含點 (".cs") |
| FullName | string | 完整路徑 |
| Directory | DirectoryInfo | 所屬目錄物件 |
| DirectoryName | string | 所屬目錄路徑 |
| Length | long | 位元組大小 |
| IsReadOnly | bool | 唯讀屬性 |
| Attributes | FileAttributes | 位元旗標組合 |
| CreationTime/Utc | DateTime | 建立時間 |
| LastAccessTime/Utc | DateTime | 最後存取時間 |
| LastWriteTime/Utc | DateTime | 最後修改時間 |
常見陷阱與避坑
| 陷阱 | 後果 | 解決 |
| GetFiles 大目錄 OOM | 一次載入百萬檔案路徑字串 | 改用 EnumerateFiles 延遲流式處理 |
| 遞歸堆疊溢位 | 極深目錄結構 ( > 1000 層) | 改用顯式 Stack/Queue 非遞歸 |
| UnauthorizedAccessException 崩潰 | 無權限目錄 (System Volume Information 等) | try-catch 吞噬並繼續 |
| PathTooLongException | 路徑 > 260 字符 | 啟用長路徑支援 (註冊表/Group Policy) 或 `\\?\` 前綴 |
| 網路路徑超時掛起 | UNC 路徑離線/慢速 | 設定逾時、非同步、取消 Token |
| 檔案系統大小寫敏感 | Linux 容器/Docker 環境 | 使用 `StringComparison.OrdinalIgnoreCase` |
現代化替代:System.IO.Abstractions (可測試)
// NuGet: System.IO.Abstractions
public class FileService
{
private readonly IFileSystem _fs;
public FileService(IFileSystem fs) => _fs = fs;
public IEnumerable GetCsFiles(string path)
=> _fs.DirectoryInfo.FromDirectoryName(path).EnumerateFiles("*.cs", SearchOption.AllDirectories);
}
// 測試時注入 MockFileSystem
var mockFs = new MockFileSystem(new Dictionary
{
[@"C:\Src\Program.cs"] = new MockFileData("class Program {}"),
[@"C:\Src\Utils.cs"] = new MockFileData("static class Utils {}")
});
var service = new FileService(mockFs);
結語
目錄遍歷看似簡單,實則暗藏記憶體、權限、路徑長度、網路延遲等地雷。**首選 `Enumerate*` 系列延遲執行 API**,配合 `try-catch` 容錯、`SearchOption.TopDirectoryOnly` 精確控制範圍、非遞歸堆疊避免溢位。現代 .NET 結合 `Span`、`Pipeline`、`Channels` 可構建高效能、低記憶體、可取消的檔案處理管線。