Go os.ReadDir 怎样高效读取目录条目

在 Go 里读取目录，最容易混淆的是把“拿到条目名称”“拿到文件元数据”和“按批次继续读取”当成同一件事。os.ReadDir 适合一次性读取一个目录并按文件名排序；已经打开目录、需要控制批量大小时，应使用 (*os.File).ReadDir；需要适配抽象文件系统时，则可以围绕 io/fs.ReadDirFS 设计。

先记住一个选择结论：目录规模可控、需要稳定顺序时用 os.ReadDir；目录可能很大或需要分页时打开目录后分批调用 File.ReadDir(n)；代码面向 fs.FS 时优先保留 fs.ReadDir 的抽象边界。下面只围绕目录条目读取，不把它扩展成递归扫描。

三个入口分别解决什么问题

os.ReadDir(name) 接受路径，返回所有可读取的 []os.DirEntry，并按文件名排序。它隐藏了打开和关闭目录的细节，调用点最短，但结果会一次性放入切片。

file.ReadDir(n) 作用在已经打开的目录文件上。n > 0 时最多返回 n 个条目，后续调用会继续读取；n 时读取剩余全部条目，并在成功到达末尾时返回 nil 错误，而不是 io.EOF。第三个入口是 fs.ReadDir(fsys, name)，它把目录读取交给文件系统实现，适合嵌入文件、测试内存文件系统或其他 fs.FS 场景。

用 os.ReadDir 一次拿到排序后的条目

当目录里的条目数在业务上可控，最直接的写法是调用 os.ReadDir。官方文档明确规定该函数返回的条目按文件名排序，因此后续生成菜单、构建索引或输出清单时，不必再重复排序。

package main

import (
    "fmt"
    "os"
)

func listNames(dir string) error {
    // 一次性读取目录；返回结果已经按文件名排序。
    entries, err := os.ReadDir(dir)
    if err != nil {
        // 路径不存在、权限不足等错误必须交给调用方判断。
        return fmt.Errorf("读取目录 %q: %w", dir, err)
    }

    for _, entry := range entries {
        // Name 只读取目录条目名称，不会把文件内容读入内存。
        fmt.Printf("%s\\t目录=%v\\n", entry.Name(), entry.IsDir())
    }
    return nil
}

这里的“高效”不是说它会无限节省内存，而是避免了不必要的二次排序和先读取名称、再逐个打开文件的额外路径。DirEntry.IsDir 能先给出目录判断；只有确实需要大小、权限或修改时间时，才继续调用 Info()。

大目录用 File.ReadDir 分批读取

如果目录条目可能很多，或者调用方本身就是分页消费，就不要先用 os.ReadDir 把全部结果装进内存。可以先打开目录，再按固定数量调用 ReadDir(batchSize)。在这个模式下，io.EOF 是“已经读完”的正常边界，不应和权限错误混为一谈。

package main

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

func streamNames(dir string, batchSize int) error {
    // batchSize 必须为正数，才能让 EOF 表示分批读取的末尾。
    if batchSize 

循环里要先消费已经返回的条目，再判断错误，因为一次调用可能同时返回最后一批条目和 io.EOF。而当 n 时，成功读完整个目录返回的是 nil，这正是它和分批模式最容易写反的地方。

DirEntry 让元数据读取保持按需

DirEntry 的价值在于先把目录索引层的信息交给调用方：名称、是否为目录、类型位都可以先判断。只有需要完整 FileInfo 时才调用 Info()，并且要把它当成可能失败的操作，因为符号链接、权限变化和文件在读取期间消失都可能影响元数据获取。

func describe(entry os.DirEntry) (string, error) {
    // 先用类型位做轻量判断，避免无条件查询完整元数据。
    if entry.IsDir() {
        return entry.Name() + " (目录)", nil
    }

    info, err := entry.Info()
    if err != nil {
        // 条目存在不代表此刻一定还能成功读取它的元数据。
        return "", fmt.Errorf("读取 %q 的元数据: %w", entry.Name(), err)
    }
    return fmt.Sprintf("%s (%d 字节)", entry.Name(), info.Size()), nil
}

如果你的需求只有名称，使用 entry.Name() 就够了；如果还要进入子目录或生成文件清单，再按需调用 IsDir、Type 和 Info。这比对每个名称重新调用 os.Stat 更容易保持调用关系清晰。

怎么选接口：排序、分页与 fs.FS

最后可以把规则压缩成一句话：小而可控的目录用 os.ReadDir，需要持续消费就用 File.ReadDir(n)，需要可替换文件系统就把入口提升到 fs.FS。不要仅为了“看起来统一”而把所有场景都改成同一个 API。

常见追问

os.ReadDir 会递归读取子目录吗？

不会。它只返回指定目录这一层的条目；递归需要调用方自行决定是否进入子目录。

File.ReadDir(0) 为什么没有 io.EOF？

当 n 小于等于零时，方法定义是读取剩余全部条目；成功读到末尾返回 nil。只有 n 大于零的分批读取才把 io.EOF 作为末尾信号。

什么时候应该调用 DirEntry.Info？

只有需要文件大小、权限或时间等完整元数据时才调用。只做名称展示或目录判断时，不必额外查询。

参考资料：https://pkg.go.dev/os#ReadDir、https://pkg.go.dev/os#File.ReadDir、https://pkg.go.dev/io/fs#ReadDirFS。