Go os.ReadDir 读取大目录怎么控内存：DirEntry、排序与错误边界

给上传文件夹做索引时，最容易出现的误判是“文件夹里文件不多，直接 os.ReadDir 就行”。文件夹一旦涨到几十万项，内存峰值、默认排序和中途权限错误会一起冒出来。Go 的 os.ReadDir 适合一次拿到目录项，File.ReadDir 更适合分批取，filepath.WalkDir 则适合递归遍历；先分清这三个边界，扫描器才不会越写越重。

一次性读取为什么写着简单，也为什么会顶内存

最小版本只有一行：

entries, err := os.ReadDir("./uploads")
if err != nil {
    return err
}
for _, entry := range entries {
    fmt.Println(entry.Name(), entry.IsDir())
}

它返回的是一整片 []os.DirEntry，并且按文件名排序。对于配置文件夹、模板文件夹这类规模可控的场景，这个默认行为用起来很顺畅；对于用户上传文件夹，排序本身就可能是额外的性能开销，所有目录项同时留在切片里也会抬高峰值。

大文件夹用 File.ReadDir 分批取

打开文件夹后调用 ReadDir(n)，可以让扫描器每次只处理固定数量的目录项。返回的 n 大于零时，读到末尾会得到 io.EOF；已经读到的一批仍然有效，不能因为同时有 EOF 就把它丢掉。

func scanDir(path string, batchSize int, visit func(os.DirEntry) error) error {
    dir, err := os.Open(path)
    if err != nil {
        return err
    }
    defer dir.Close()

    for {
        entries, readErr := dir.ReadDir(batchSize)
        for _, entry := range entries {
            if err := visit(entry); err != nil {
                return err
            }
        }
        if errors.Is(readErr, io.EOF) {
            return nil
        }
        if readErr != nil {
            return readErr
        }
    }
}

这里的关键不是把批大小调得越小越好。批太小会增加系统调用和调度次数，批太大又失去控制内存的意义。索引任务可以先从 256 或 1024 开始，用实际文件夹规模和处理耗时再做调整。

DirEntry 先做便宜判断，Info 留到确实需要时

DirEntry 已经能提供名称、是否为文件夹和类型信息。若索引只需要记录路径和目录标记，直接使用这些方法即可：

err := scanDir("./uploads", 512, func(entry os.DirEntry) error {
    if entry.IsDir() {
        return nil
    }
    name := entry.Name()
    if !strings.HasSuffix(name, ".json") {
        return nil
    }
    return appendIndex(name)
})

只有要记录大小、修改时间或权限时，才调用 entry.Info()。这一步可能触发额外的文件系统查询；网络存储、海量小文件文件夹和高并发索引任务尤其容易被这类细节拖慢。

递归扫描时，把错误当成一个节点处理

目录树需要递归时，filepath.WalkDir 会把访问错误交给回调。回调收到的 entry 可能仍然代表那个文件夹，索引器可以记录错误并返回 fs.SkipDir，让其他分支继续：

err := filepath.WalkDir(root, func(path string, entry os.DirEntry, walkErr error) error {
    if walkErr != nil {
        log.Printf("skip path=%s reason=%v", path, walkErr)
        if entry != nil && entry.IsDir() {
            return filepath.SkipDir
        }
        return nil
    }
    if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
        return nil
    }
    return appendIndex(path)
})
if err != nil {
    return fmt.Errorf("walk uploads: %w", err)
}

是否跳过文件夹要看业务：权限错误可以跳过并保留部分索引，根路径打不开则应该直接失败。把两者都当成致命错误，扫描器会因为一个坏分支丢掉全部结果；把两者都忽略，又会让索引看起来完整却实际缺项。

排序、顺序和可重复性怎么取舍

os.ReadDir 会按文件名排序，File.ReadDir 返回文件夹本身提供的顺序。需要分页、断点或稳定测试结果时，排序有价值；只是把所有新文件丢进队列时，未必值得为全量排序付出额外开销。

• 需要稳定输出：按名称或相对路径排序，再生成索引快照。
• 只需要尽快消费：分批读取，处理完一批就释放引用，不额外复制名称。
• 需要断点续扫：记录最后处理的路径或文件系统游标，同时接受文件夹变化带来的重复检查。

不要把“未排序”误解成“永远不会变化”。文件夹在扫描过程中可能新增或删除文件；如果结果必须一致，应先生成快照或把扫描和发布索引拆成两个阶段。

用测试固定 EOF 和部分结果规则

func TestReadDirBatchKeepsEntriesBeforeEOF(t *testing.T) {
    root := t.TempDir()
    for _, name := range []string{"a.json", "b.json", "c.json"} {
        if err := os.WriteFile(filepath.Join(root, name), []byte("{}"), 0600); err != nil {
            t.Fatal(err)
        }
    }

    var got []string
    if err := scanDir(root, 2, func(entry os.DirEntry) error {
        got = append(got, entry.Name())
        return nil
    }); err != nil {
        t.Fatal(err)
    }
    if len(got) != 3 {
        t.Fatalf("got %v", got)
    }
}

这个测试专门防止一个常见bug：读取最后一批时同时拿到目录项和 io.EOF，代码却先判断错误并直接返回，结果漏掉一批文件。

相关问题

os.ReadDir 会递归读取子文件夹吗？

不会，它只读取指定文件夹的一层。需要递归时使用 filepath.WalkDir 或自己维护待处理文件夹队列。

ReadDir(0) 适合大文件夹吗？

n 表示一次读取剩余全部目录项，不适合用来限制大文件夹内存。需要分批时传入正数。

为什么不直接对所有 entry 调用 Info？

因为很多索引只需要名称和类型。批量调用 Info 会增加文件系统访问，应该把它放在过滤之后，并用实测数据决定是否需要并发。

文件夹扫描的选择，取决于结果边界

小文件夹、稳定输出可以直接用 os.ReadDir；大文件夹、持续消费用 File.ReadDir(n)；递归树和部分容错用 WalkDir。真正需要固定的不是某个 API，而是三件事：一次保留多少目录项、是否需要排序、遇到局部错误时结果能否继续使用。先把这三个问题写进测试，文件夹规模涨大以后，扫描器才不会悄悄变成内存峰值来源。