Go os.ReadDir 为什么目录项默认按文件名排序

排查目录扫描结果时，经常会看到 os.ReadDir 每次都按文件名返回条目，于是误以为 Linux、macOS 或 Windows 的文件系统本身保证了这个顺序。实际情况是：os.ReadDir(name) 主动把读到的条目按 DirEntry.Name() 排序；真正从已打开目录读取的 os.File.ReadDir(n) 则按目录顺序返回。这个差异正是包级函数和文件对象方法的职责边界。

os.ReadDir 的排序是 API 契约，不是系统巧合

包级函数的文档直接写明：读取指定目录并返回全部目录项，结果按文件名排序。这里的“文件名”对应 DirEntry.Name() 返回的字符串，排序是 Go 代码层面的确定性处理，不依赖目录项在磁盘上的排列方式。因此同一组名称在不同操作系统或不同文件系统上，调用 os.ReadDir 后都可以得到一致的名称顺序。

它也解释了一个常见现象：目录里先创建的文件不一定先出现，带数字的文件名也不是按人类直觉的数值顺序排列。例如 part-10 会排在 part-2 前面，因为比较的是字符串，而不是把尾部数字转成整数。

源码里排序发生在一次性读取完成之后

当前标准库实现的关键路径很短：先打开目录，再调用文件对象的 ReadDir(-1) 读取剩余全部条目，最后用条目的 Name() 做字符串比较排序。也就是说，底层读取顺序和对外返回顺序不是同一个阶段。

package main

import (
	"fmt"
	"os"
)

func main() {
	entries, err := os.ReadDir("./data")
	if err != nil {
		// 目录不存在或没有权限时，先保留原始错误，便于定位路径问题。
		fmt.Println("读取目录失败:", err)
		return
	}

	for _, entry := range entries {
		// Name 是排序使用的名称，不会把数字后缀当作数值比较。
		fmt.Println(entry.Name())
	}
}

上面的调用适合“把目录完整读出来并稳定展示”的场景。它返回的是一个切片，排序成本和目录项数量相关；目录很大时，还会同时保留完整的条目集合。

os.File.ReadDir(n) 为什么看起来又没有排序

打开目录后调用方法，语义就变成了从这个目录文件当前位置继续读取。文档规定，n > 0 时最多返回 n 个条目，后续调用继续读取后面的条目；读到末尾时返回 io.EOF。这些条目按目录顺序返回，而不是每次都重新按名称排序。

package main

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

func printInBatches(path string, batchSize int) error {
	f, err := os.Open(path)
	if err != nil {
		return err
	}
	defer f.Close() // 目录文件也要及时关闭，避免长期占用文件描述符。

	for {
		entries, err := f.ReadDir(batchSize)
		for _, entry := range entries {
			// 这里是目录顺序；如果业务要求名称有序，应先收集再统一排序。
			fmt.Println(entry.Name())
		}
		if err == io.EOF {
			return nil // 正常读完，不把 EOF 当成业务失败。
		}
		if err != nil {
			return err // 保留已读数据，同时把真实读取错误交给上层。
		}
	}
}

因此，把 ReadDir(100) 当成“按文件名排序的第 1 页”并不稳妥。它只是底层目录顺序的前 100 项；要做稳定分页，需要先得到完整有序集合，或者建立自己的索引与排序键。

项目中如何选择读取与排序方式

如果需要自定义排序，可以先用 os.ReadDir 获取稳定输入，再读取每个条目的信息并排序；如果只关心吞吐量，则优先使用文件对象的分批方法，避免无意中把“稳定排序”当成免费特性。测试时也要明确断言：验证顺序时断言名称序列，验证流式处理时则不要把目录底层顺序写成跨平台承诺。

常见问题

os.ReadDir 会按创建时间排序吗？

不会。它按 Name() 的字符串排序；创建时间需要另行读取文件信息并自行比较。

文件名中的数字会按自然数顺序排列吗？

不会。part-10 与 part-2 的比较仍是字符串比较，需要拆分数字并实现业务排序。

ReadDir(0) 和 ReadDir(-1) 有什么区别？

两者都表示读取剩余全部条目，成功时返回 nil 错误；只有传入正数时才是限制数量的分批读取。

官方依据在哪里？

https://pkg.go.dev/os#ReadDir 与 https://pkg.go.dev/io/fs#ReadDir 描述了按文件名排序的契约，os.File.ReadDir 的文档则说明了目录顺序和分批读取规则。