Go os.ReadDir 流式读取大目录并控制内存

面对一个包含大量文件的目录，直接调用 os.ReadDir(dir) 很方便，但它会把读取到的目录项作为一个完整切片返回。需要控制峰值内存时，应改成 os.Open 配合 File.ReadDir(batchSize)：每次只拿一小批 fs.DirEntry，处理完后再继续读取。

官方资料：https://pkg.go.dev/os

关键区别是：os.ReadDir(name) 适合一次拿到完整、按文件名排序的结果；流式遍历要使用打开目录后的 ReadDir(n)，把批量大小当作内存控制旋钮。n>0 时，读到目录末尾会返回 io.EOF。

为什么大目录不应默认使用 os.ReadDir

os.ReadDir(name) 的语义是读取命名目录并返回全部目录项，而且结果按文件名排序。它的代码短、调用次数少，适合配置目录、模板目录这类规模可预期的场景；问题在于目录项越多，返回切片就越大，后续筛选逻辑还可能继续持有这批对象。

流式方案把“遍历目录”和“处理目录项”放在同一个循环中，内存中主要保留当前批次。这里的“控制内存”是降低一次性切片的峰值，不代表操作系统目录缓存、单个文件元数据或下游队列都自动受到限制。

用 File.ReadDir(n) 固定每批的目录项数量

下面的示例把批量大小设为 256，每轮只处理最多 256 个目录项。示例没有把所有名称追加到一个总切片中，因此适合“读到一项就交给处理函数”的索引、扫描或归档前置任务。

package main

import (
	"errors"
	"fmt"
	"io"
	"os"
)

func walkDirInBatches(path string, batchSize int) error {
	if batchSize  0 时，最后一批之后用 EOF 表示目录已经读完。
			return nil
		}
		if readErr != nil {
			return fmt.Errorf("read directory %q: %w", path, readErr)
		}
	}
}

func main() {
	if err := walkDirInBatches("./data", 256); err != nil {
		fmt.Println("scan failed:", err)
	}
}

当最后一批恰好读满时，某次调用可能先返回完整的 entries，下一次才返回空切片和 io.EOF；因此必须先处理本次返回的 entries，再判断错误。只要不是 EOF，其他错误都应保留路径上下文并停止遍历。

DirEntry 先筛选，Info 只在确有需要时调用

fs.DirEntry 已经提供 Name、IsDir、Type 等入口。很多目录扫描只需要名字和类型，不需要把每个条目都升级为 FileInfo。如果确实要拿大小、修改时间等元数据，再对单项调用 Info()，并处理它自己的错误。

func collectLargeFiles(dirPath string, minBytes int64, batchSize int) ([]string, error) {
	dir, err := os.Open(dirPath)
	if err != nil {
		return nil, fmt.Errorf("open %q: %w", dirPath, err)
	}
	defer dir.Close() // 让目录句柄在函数退出时释放。

	var result []string
	for {
		entries, readErr := dir.ReadDir(batchSize)
		for _, entry := range entries {
			if entry.IsDir() {
				continue
			}
			info, infoErr := entry.Info()
			if infoErr != nil {
				return nil, fmt.Errorf("stat %q: %w", entry.Name(), infoErr)
			}
			if info.Size() >= minBytes {
				// 这里只保留命中的路径；若结果也可能很大，应改为回调或写入流。
				result = append(result, entry.Name())
			}
		}

		if errors.Is(readErr, io.EOF) {
			return result, nil
		}
		if readErr != nil {
			return nil, fmt.Errorf("read %q: %w", dirPath, readErr)
		}
	}
}

这个函数仍然会积累命中的路径，所以它只是“读取阶段分批”，不是全链路的硬内存上限。若结果集也可能很大，可以把返回切片换成回调、写入文件或有界队列；否则批量读完后又会在结果切片上重新占用内存。

批量大小怎么选，哪些场景仍然适合一次读取

批量值不应照搬。可以从 128 或 256 起步，再根据单项处理成本、下游积压和进程内存曲线调整。重点是让“本批次”“结果集合”“下游队列”分别有清晰的生命周期。

常见疑问

File.ReadDir(n) 会自动递归子目录吗？不会。它只读取当前目录；递归需要由业务代码决定是否把子目录加入待处理队列，而队列也应设置上限。

为什么不能忽略 ReadDir 返回的错误？因为 io.EOF 是正常结束，权限错误、目录变化导致的其他错误则可能意味着结果不完整。先处理 entries，再区分 EOF 和其他错误，才能避免漏掉最后一批。

调用 Info 会不会破坏流式读取？不会破坏读取 API 的分批语义，但它可能触发额外的元数据访问。只在筛选确实需要大小、时间或权限信息时调用，并对单项错误给出路径上下文。