Go os.File.Readdirnames 读完目录后为什么返回 io.EOF

使用正数批量调用 os.File.Readdirnames(n) 时，io.EOF 通常表示目录名称已经读完，是遍历的正常结束信号。它不等于目录损坏，也不要求重新打开后再重试。正确的循环应先消费本次返回的名称，再判断错误：遇到 EOF 返回成功，遇到其他读取错误则保留上下文向上报告。

官方地址：https://pkg.go.dev/os

问题现场：名称打印完了，程序却报告失败

假设一个目录中只有少量文件，程序每次请求一百个名称。前面的名称都已经交给业务处理，下一次调用却获得空切片和 EOF。如果外层直接把所有非空错误当作扫描失败，就会出现“文件都读到了，但任务状态仍然失败”的现象。

这里应先检查两个位置：传入的 n 是否为正数，错误分支是否区分 EOF。不要先怀疑文件权限，也不要用无限重试掩盖结束信号。真正的权限、句柄状态等问题需要根据实际错误判断，不能统一替换为“读完了”。

初步判断：同一个方法有两套读取约定

官方文档将正数分批读取与非正数读取分别定义。正数限制单次返回数量；非正数请求取出当前句柄剩余的全部名称，成功读到末尾时返回 nil 错误。因而把参数从 100 改成 -1 后，不能继续沿用“循环直到 EOF”的控制方式。

动手验证：把分批遍历封装成完整函数

下面的程序接收一个目录路径，逐批打印名称。示例固定批量为 128，重点是错误处理的位置，并不声称这个数字适合所有负载。代码是可供读者在自己的环境运行的示例，本文没有执行本地目录测试，也没有提供虚构输出。

package main

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

func visitNames(path string, visit func(string) error) (resultErr error) {
    dir, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("打开目录: %w", err)
    }
    // 所有返回路径都关闭句柄，同时保留已有的主要错误。
    defer func() {
        if err := dir.Close(); err != nil && resultErr == nil {
            resultErr = fmt.Errorf("关闭目录: %w", err)
        }
    }()

    for {
        names, readErr := dir.Readdirnames(128)
        // 先消费已经取得的名称，不因同时返回错误而丢弃它们。
        for _, name := range names {
            if err := visit(name); err != nil {
                return fmt.Errorf("处理名称 %q: %w", name, err)
            }
        }
        if errors.Is(readErr, io.EOF) {
            return nil
        }
        if readErr != nil {
            return fmt.Errorf("读取目录名称: %w", readErr)
        }
    }
}

func main() {
    // 路径来自命令行，避免把机器专属路径写进示例。
    if len(os.Args) != 2 {
        fmt.Fprintln(os.Stderr, "请提供一个目录路径")
        os.Exit(2)
    }
    err := visitNames(os.Args[1], func(name string) error {
        _, err := fmt.Fprintln(os.Stdout, name)
        return err
    })
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

函数只把 readErr 中的 EOF 转换为正常结束。如果输出端写入失败，回调产生的错误会立即上报；即便业务回调也返回 EOF，它仍属于业务失败。这种分离能避免“读目录结束”和“下游停止接收”混成一个状态。

定位原因：目录句柄保留读取位置

同一个打开的目录句柄承载遍历状态。连续读取是在已有位置上继续取名称，并不会从头开始。最后一批取出了多少名称，不应被用来替代明确的错误判断；尤其不要仅凭数量小于批量就宣布任务成功，因为还有读取错误需要处理。

也不必依赖“最后一个非空批次一定携带 EOF”这样的假设。让循环能够处理非空结果，随后再识别结束或失败，代码就不会绑定某一平台某一次调用的表现。读取名称之后取得的只是名称字符串，不是后续文件操作一定成功的凭证。

当目录内容在扫描期间变化时，也不要把这段遍历包装成一致性快照。若任务需要后续打开某个名称，应在那一步单独处理文件已不存在等错误。这个问题和 EOF 的含义分属不同操作层次。

修复方案：按任务选定读取方式

需要控制单次名称切片的规模时，保留正数批量循环。需要一次收集当前剩余名称时，可以使用非正数参数，但要接受名称切片随目录规模增长。不要把非正数调用放进等待 EOF 的无条件循环：一次成功后继续读取，仍可能获得空结果和 nil，从而形成无意义循环。

还要避免在每轮循环里重新打开目录。那会创建新的遍历状态，让程序反复处理开头的名称。打开一次、读取多次、在函数结束时关闭，是这里清晰的资源生命周期。若确实要重新扫描，应该把它作为一次新的任务，并考虑业务处理是否允许重复。

验证结果应该看哪些边界

以下是按接口约定整理的预期结果，用于读者自行检查代码，不是本地实测记录。

• 空目录配合正数批量：无需处理任何名称，读取结束应使函数正常返回。
• 名称数少于或超过一个批量：每个已返回名称都进入业务处理，最终结束不会被报告为扫描故障。
• 目录打开失败：保留打开错误，不把失败解释为“目录为空”。
• 回调处理失败：停止当前任务并保留名称上下文，不继续吞掉业务错误。
• 非正数一次读取：以本次返回结果和错误为依据，不追加等待 EOF 的循环。

常见问题

EOF 后继续读会自动从头开始吗？不会。需要重新扫描时应建立新的遍历，而不是把同一目录句柄当作自动回绕的容器。

只检查 len(names) 是否为零行不行？不够。空结果可能伴随结束，也可能伴随真实错误；必须查看错误值。结果非空时也要处理本次错误。

为什么示例还处理 Close 的错误？为了让资源释放结果有明确归属。读取或业务已经失败时优先保留主要错误；前面成功而关闭失败时，再把关闭错误返回。

排查这个问题时，抓住参数、返回值消费顺序和句柄生命周期即可。正数分批读取把 EOF 作为正常终点，名称先处理，其他错误照常上报，目录句柄最终释放。

参考：Go 官方 Readdirnames 文档；Go 官方目录读取实现及接口注释。