Go 文件系统ReadDir 读取大目录占用内存怎么办

我遇到过一种很容易误判的 Go 内存问题：目录扫描逻辑本身没有明显的大对象，但目录从几万项增长到几百万项后，进程内存也跟着一路上升。最后发现，代码调用的是 os.ReadDir(path)，它会把目录条目一次性返回为一个切片。真正需要控制的不是“能不能读目录”，而是“同一时刻要在内存里保留多少条目”。

先判断内存增长是不是由完整切片造成的

os.ReadDir 的便利之处也是它的边界：它读取指定目录并返回全部 DirEntry，而且按文件名排序。目录项越多，返回切片和其中的条目引用就越大。如果后续代码还把结果放进队列、缓存或并发任务中，峰值会继续放大。

先看调用点是否类似下面这样。这个写法不一定错误，但它把目录规模直接变成了单次内存预算：

package main

import "os"

func scanAll(path string) error {
	// os.ReadDir 会一次性返回目录中的全部条目，适合小目录或确实需要全量排序的场景。
	entries, err := os.ReadDir(path)
	if err != nil {
		return err
	}
	// 只要 entries 仍被持有，整批目录条目就可能继续占用内存。
	for _, entry := range entries {
		_ = entry.Name()
	}
	return nil
}

排查时重点看三件事：切片是否跨越整个任务生命周期、条目是否被再次复制到下游容器、以及是否为每个条目都调用了 Info。如果三者同时存在，单纯调小 Go 的 GC 参数通常不是根治办法。

改成按批读取大目录

更稳妥的改法是打开目录后循环调用 File.ReadDir(batchSize)。当参数大于 0 时，每次最多返回指定数量的条目；读到目录末尾后，下一次读取会返回空切片和 io.EOF。因此，批次处理函数不应把 io.EOF 当成故障。

package main

import (
	"io"
	"os"
)

func scanInBatches(path string, batchSize int, handle func(os.DirEntry) error) error {
	if batchSize 

这里特意先处理非空批次，再判断 io.EOF。这样即使最后一次调用返回“剩余条目加 EOF”，也不会漏掉最后一批。实际项目中，batchSize 可以从 128、256 或 512 开始，根据单批处理耗时和堆峰值调整。

不要为每个条目无条件读取完整信息

os.DirEntry 已经提供了名称、类型和目录判断等轻量入口。很多清理、分发或过滤任务只需要这些信息，不必马上转换成完整的 FileInfo。只有业务确实要比较文件大小、权限或修改时间时，再调用 Info，并单独处理它的错误。

func handleEntry(entry os.DirEntry) error {
	// 先用目录项自带的信息完成便宜的过滤，避免无意义的元数据读取。
	if entry.IsDir() {
		return nil
	}
	if entry.Type().IsRegular() {
		// 只有进入真正的业务分支后，才读取完整 FileInfo。
		info, err := entry.Info()
		if err != nil {
			return err
		}
		_ = info.Size()
	}
	return nil
}

这不会让目录扫描变成零成本：某些文件系统上，类型信息可能不完整，调用 Info 仍可能触发额外的系统调用。但把它放到必要分支里，至少能避免“每个条目都查询一次完整元数据”成为默认路径。

排序、错误和回滚边界要提前说清楚

os.ReadDir(path) 的结果按文件名排序，而 File.ReadDir(n) 返回目录顺序。两者不能只替换函数名就认为语义完全相同。如果下游依赖全局排序，例如按名称生成稳定清单，就要选择以下一种策略：

• 业务不要求排序：直接接受目录顺序，把稳定性要求放到条目处理结果中。
• 只要求局部排序：每批读取后在批内排序，但要明确这不是全局排序。
• 必须全局排序：先把必要字段写入外部临时存储或分片文件，再做外部排序，不能重新把全部条目堆回内存。

错误处理也要保留“已经处理到哪里”的信息。生产代码可以把当前批次的第一个名称写入结构化日志，并携带扫描任务 ID；不要把完整路径、用户数据或密钥写进日志。若下游要求失败重试，重试应从可确定的游标、分片或任务记录恢复，而不是无条件从目录头部重扫。

回滚很简单：保留旧的全量实现作为配置开关，只对一个低风险目录或小比例任务启用批量模式。确认下游没有依赖全局排序后，再逐步扩大范围。出现处理顺序影响结果、批次耗时异常或句柄未释放时，先切回旧开关，同时保留指标和错误样本。

上线后看哪些信号

改动后不要只看一次 RSS。建议按固定目录和固定并发量对比以下指标：

如果峰值下降但总耗时明显增加，先调整批次大小和下游并发，不要马上把批次扩大到“看起来更快”的程度。目标是让内存上限可预测，并且在异常时能停在一个可恢复的边界。

常见问题

把 os.ReadDir 换成 File.ReadDir(1000) 就一定不占内存吗？

不会。它只把目录读取切成有限批次；如果后续把每一批继续放进全局切片、队列或缓存，内存仍会随目录规模增长。要让峰值受控，批次处理完必须释放外部引用。

File.ReadDir 的 n 应该设置多大？

没有通用固定值。可以从 128 或 256 开始，用单批耗时、堆峰值和下游吞吐做压测，再按业务目标调整。

只需要文件名时是否应该调用 Readdirnames？

可以考虑。它返回名称切片并支持正数 n 分批读取；如果还需要类型判断或延迟元数据访问，File.ReadDir(n) 返回 DirEntry 会更合适。