Go os.File.ReadDir 为什么会让目录排序变慢：流式读取与内存取舍

目录索引任务改成按批读取后，内存曲线通常会好看一些，但“读取变流式”不等于“最终排序免费”。真正容易踩坑的地方是：os.ReadDir 直接给你排好序的完整切片，而 (*os.File).ReadDir(n) 把读取和排序责任拆开了。

先定义目录索引任务的边界

假设有一个构建产物目录索引器：它扫描单层目录，记录普通文件的名称和大小，供后续生成清单。目录通常有几千项，但发布高峰会遇到几十万项；此时最先要确认的不是“哪个 API 更快”，而是结果是否必须全局按名称排序。

如果只需要统计数量、筛选后立刻写入下游，按批读取就足够。如果要把全部文件名展示成稳定列表，批量读取只解决了读取阶段的峰值，后面仍要收集结果并排序。这个边界不写清楚，优化很容易变成把问题从读取函数挪到排序函数。

一次性读取为什么看起来简单，却会推高峰值

os.ReadDir 负责打开目录、读完全部条目，并按文件名排序后返回。调用点很干净：

entries, err := os.ReadDir(root)
if err != nil {
    return fmt.Errorf("read directory %q: %w", root, err)
}
for _, entry := range entries {
    if entry.Type().IsRegular() {
        consume(entry.Name())
    }
}

代价不只是一段切片。文件名字符串、目录项元数据以及排序期间仍被引用的对象，都会叠加到堆使用量上。小目录中这点开销几乎不可见；目录规模和并发扫描数一起上升时，GC 频率和请求尾延迟就可能先暴露出来。

什么时候保留 os.ReadDir

需要稳定顺序的导出、目录规模受控的配置加载、或者代码确实要一次遍历全部条目的场景，可以继续使用它。重点是把它当成“全量加载并排序”，而不是误称为流式接口。

用 File.ReadDir(n) 把读取阶段拆成批次

打开目录后，传入正数的 ReadDir(n) 每次最多返回 n 个条目。读到末尾时，返回值可能同时带有最后一批条目和 io.EOF，因此必须先处理切片，再判断错误：

func countRegularFiles(root string, batchSize int) (int, error) {
    if batchSize 

每轮只保留当前批次的 entries。如果业务在循环中完成过滤、统计或写出，上一批就不再需要。批大小可以从 256 或 512 开始做基准，但不要把这个数字当成跨机器的固定答案。

三个错误出口要分开

• 批次已经返回条目，同时错误为 io.EOF：先处理条目，再把 EOF 视为正常结束。
• 错误为权限变化、文件系统断开等其他值：保留路径和原始错误，交给上层决定是否重试。
• 批大小为 0 或负数：在打开目录前拒绝，避免把“读取全部”的语义误套到限流参数上。

排序需求会把成本带回业务层

File.ReadDir(n) 返回的是读取批次，不应把批次顺序当成全局文件名顺序。若索引器只写出普通文件计数，完全可以不排序；若只要名称最小的前 100 项，可以维护固定容量的候选集，最后只排序候选项。

如果需求是导出全部文件名并保持字典序，常见做法有两种：一是接受收集全部名称再排序，二是把各批结果写入临时分片后做外部归并。前者实现简单但仍占内存，后者降低内存峰值，却要增加临时空间、清理和失败恢复的门禁。

把验收门禁放进测试和基准

先用同一目录核对两种路径的结果，再观察堆分配和进程 RSS：

go test ./...
go test -bench . -benchmem
go run . --root ./artifacts --mode batch --batch 256

测试至少覆盖空目录、批次大于条目数、批次为零、目录不存在，以及最后一批同时带条目和 io.EOF 的情况。性能基准要逐步扩大目录规模，并记录扫描并发数；只看一次运行时间，可能把 GC 抖动或缓存命中误判成 API 差异。

若扫描位于 HTTP 请求中，批大小最好来自服务端受控配置。请求参数可以选择模式，但不应允许调用方把批大小放大到失去内存上限的程度。目录关闭、临时分片清理和下游写入失败，也应各自留下可定位的错误信息。

常见问题

File.ReadDir(0) 是不是按小批次读取？

不是。传入 0 表示读取剩余全部条目；想控制每批数量，应传入正整数。

批量读取后还能得到全局排序吗？

能，但需要业务层收集后排序，或设计外部归并。批次本身的顺序不能替代全局排序。

读到 io.EOF 要记录成失败吗？

对正数批量读取来说，末尾的 io.EOF 是正常收口信号；只有其他错误才应进入失败处理。

最后的选择标准

目录规模可控且需要稳定顺序时，os.ReadDir 直观可靠；目录很大、只需过滤或统计时，用 File.ReadDir(n) 把读取阶段控制在批次内。只要需求包含全量排序，就把排序成本单独列出来，用基准结果决定是保留内存方案，还是升级到外部归并。