Go os.ReadDir 怎样按名称读取目录项并处理遍历错误

我在做目录清单时最容易踩的坑，不是不会调用 os.ReadDir，而是把“返回了部分目录项”和“读取成功”当成同一件事。这个函数确实会按文件名排序，适合生成稳定的清单；但目录读取中途发生错误时，它也可能把已经读到的部分项和错误一起返回。只要把这两个语义分开，代码就不会把半份目录误当成完整快照。

这篇只讨论 os.ReadDir 返回的目录项、错误处理和它与 (*os.File).ReadDir 的差别，不展开递归遍历、符号链接策略或文件内容读取。

先把 os.ReadDir 的返回值读完整

os.ReadDir(name) 返回 []os.DirEntry 和 error。官方文档明确了两点：结果按文件名排序；如果读取目录时出错，会返回出错前已经读到的目录项以及错误。因此，len(entries) > 0 不能证明目录已经完整读完，真正的完整性信号仍然是 err == nil。

我通常先写一个严格模式的目录清单函数。它的约定很简单：只要目录没有完整读完，就不把部分结果交给上层。

package main

import (
	"fmt"
	"os"
)

// listNames 只返回完整目录清单；任何读取错误都会保留给调用方处理。
func listNames(dir string) ([]string, error) {
	entries, err := os.ReadDir(dir)
	if err != nil {
		// 发生中途错误时 entries 可能非空，但它不是完整快照。
		return nil, fmt.Errorf("读取目录 %q: %w", dir, err)
	}

	names := make([]string, 0, len(entries))
	for _, entry := range entries {
		// os.ReadDir 已按文件名排序，这里只提取稳定的末级名称。
		names = append(names, entry.Name())
	}
	return names, nil
}

func main() {
	names, err := listNames("./assets")
	if err != nil {
		// 不把半份结果继续写入索引或缓存，避免制造假清单。
		fmt.Println(err)
		return
	}
	fmt.Println(names)
}

这个写法适合生成索引、构建目录快照或把清单交给后续批处理。需要注意的是，DirEntry.Name() 只给出目录项的末级名称，不是完整路径；如果后面需要拼接路径，应保留目录参数和名称的组合关系。

DirEntry 先轻量判断，Info 错误单独处理

os.DirEntry 可以先提供名称、是否为目录和类型位。它比一开始就取完整 FileInfo 更适合做目录筛选：例如清单只需要名称时，不必额外调用 Info()。但如果业务确实需要大小或修改时间，Info() 自己也可能返回错误，不能把它和目录读取错误混为一谈。

package main

import (
	"fmt"
	"os"
)

// printRegularFiles 展示如何把目录读取错误与单项 Info 错误分层处理。
func printRegularFiles(dir string) error {
	entries, err := os.ReadDir(dir)
	if err != nil {
		// 目录本身没有完整读完，先停止，避免输出不完整文件集合。
		return fmt.Errorf("目录清单不完整: %w", err)
	}

	for _, entry := range entries {
		// 先用类型位做便宜筛选，避免对目录项一律读取完整元数据。
		if entry.IsDir() {
			continue
		}
		info, err := entry.Info()
		if err != nil {
			// 目录项可能在读取后被删除或改名；记录该项并继续其他项。
			fmt.Printf("跳过 %s：%v\\n", entry.Name(), err)
			continue
		}
		fmt.Printf("%s %d bytes\\n", entry.Name(), info.Size())
	}
	return nil
}

这里的取舍是：目录读取失败属于整体结果不可信，直接返回；某个目录项的元数据读取失败只影响这一项，则记录后继续。若你的业务要求每个文件都有完整元数据，也可以把 Info() 错误升级为整体失败，但要把这个约定写进函数文档。

完整清单和增量读取不要混用

如果调用的是 os.ReadDir，可以依赖按文件名排序的结果。若改成先 os.Open 再调用 file.ReadDir(n)，语义就变了：它按目录顺序返回，后续调用会继续读取；n > 0 时到目录末尾会通过 io.EOF 表示结束，n 则尝试返回剩余全部项并在成功时返回 nil 错误。

package main

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

// readInBatches 只在确实需要分批消费时使用 File.ReadDir。
func readInBatches(dir string, batchSize int) error {
	file, err := os.Open(dir)
	if err != nil {
		return fmt.Errorf("打开目录 %q: %w", dir, err)
	}
	defer file.Close() // 释放目录文件描述符，避免长时间任务泄漏资源。

	for {
		entries, err := file.ReadDir(batchSize)
		for _, entry := range entries {
			// 这里的顺序是目录顺序，不应当当作文件名排序结果。
			fmt.Println(entry.Name())
		}
		if err == io.EOF {
			// n > 0 且没有更多项时，EOF 是正常结束信号。
			return nil
		}
		if err != nil {
			return fmt.Errorf("分批读取目录: %w", err)
		}
	}
}

我的判断标准是：要稳定、一次拿到完整清单，就用 os.ReadDir 并把非空错误视为失败；要控制批量、持续消费或保留目录文件句柄，才使用 File.ReadDir(n)，同时明确处理 io.EOF。两者都返回 DirEntry，但排序和结束条件不能互换。

常见疑问

os.ReadDir 返回部分 entries 时能不能继续用？

可以，但只能在业务明确支持“尽力读取”时使用，并且必须同时保留非空错误。索引或配置快照通常需要完整性，应直接失败。

只要需要文件大小就必须立刻调用 Info 吗？

不必。先用 Name、IsDir 和 Type 做筛选，再对真正需要的项调用 Info，并单独处理该调用的错误。

最后记住一句：os.ReadDir 的排序保证解决了结果稳定性，error 才决定这份结果是否完整；把这两个信号分开，目录处理代码就更容易维护。