Go fs.Glob 为什么会忽略目录读取错误

调用 fs.Glob 后得到空匹配，却没有得到目录权限或读取失败的错误，通常不是代码漏写了 err 判断，而是 API 的既定语义：默认实现会忽略遍历目录时发生的文件系统错误，唯一预期返回的错误是匹配模式非法的 path.ErrBadPattern。如果业务必须知道哪些目录读失败，就不能把 Glob 当成审计型遍历器。

为什么 fs.Glob 看不到目录错误

fs.Glob(fsys, pattern) 的目标是“尽可能找出匹配名称”，而不是保证整棵目录树被无误读取。官方文档明确说明，目录读取时的 I/O 错误会被忽略；因此某个子目录打不开时，已经找到的匹配仍可能返回，那个子目录下面的结果则直接缺失。

可以把结果分成三种情况：模式正确且有匹配时返回匹配列表和 nil；模式正确但没有匹配时返回空结果和 nil；模式语法错误时返回 path.ErrBadPattern。所以“len(matches)==0 且 err==nil”只能说明当前遍历没有产出匹配，不能证明目录都读成功了。

默认 FS 与 GlobFS 的调用分支

默认情况下，fs.Glob 检查文件系统是否实现了 fs.GlobFS。没有实现时，它使用 fs.ReadDir 逐层读取目录并匹配路径；读取失败被吞掉，调用者无法从返回值恢复失败目录。若实现了 Glob(pattern)，标准库会直接调用这个方法，匹配、缓存和错误返回就由该实现负责。

package main

import (
    "fmt"
    "io/fs"
    "path"
)

func inspect(pattern string, fileSystem fs.FS) {
    // 只有模式语法错误是默认 fs.Glob 的预期错误来源。
    matches, err := fs.Glob(fileSystem, pattern)
    if err != nil {
        if err == path.ErrBadPattern {
            fmt.Printf("模式非法：%v\n", err)
            return
        }
        // 自定义 GlobFS 可以返回自己的错误，不能把它误认为默认分支。
        fmt.Printf("自定义 Glob 实现返回错误：%v\n", err)
        return
    }
    // 空结果不等于所有目录都读取成功。
    fmt.Printf("匹配结果：%v\n", matches)
}

这也是排查时容易混淆的地方：fs.Glob 的文档约定描述的是标准行为，但一个自定义的 GlobFS 可以定义自己的实现。接入第三方或网络文件系统时，应先阅读它的 Glob 方法契约，不要只根据函数名推断错误处理。

需要保留目录错误时改用 WalkDir

如果结果要用于清理、备份、索引或权限审计，建议用 fs.WalkDir。它会在目录读取失败时再次调用回调，并把错误放在 err 参数里。下面的写法同时收集匹配项和失败目录；生产代码还可以把错误写入日志或指标。

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "path"
    "strings"
)

func collect(fsys fs.FS, pattern string) ([]string, []error) {
    var matches []string
    var readErrors []error

    // WalkDir 的 err 来自当前路径，返回它会终止整次遍历。
    err := fs.WalkDir(fsys, ".", func(name string, entry fs.DirEntry, err error) error {
        if err != nil {
            // 先保留路径上下文，便于区分“没匹配”和“读不到”。
            readErrors = append(readErrors, fmt.Errorf("读取 %s：%w", name, err))
            return nil // 继续检查其他目录，不让一个失败点遮住全局结果
        }
        if entry.IsDir() {
            return nil
        }
        matched, matchErr := path.Match(pattern, strings.TrimPrefix(name, "./"))
        if matchErr != nil {
            return matchErr // 模式错误属于调用参数问题，应立即返回
        }
        if matched {
            matches = append(matches, name)
        }
        return nil
    })
    if err != nil {
        readErrors = append(readErrors, err)
    }
    return matches, readErrors
}

示例选择继续遍历，是因为索引类任务通常希望一次报告尽可能多的失败点。如果业务要求“发现一个权限错误就停止”，把回调中的 return nil 换成返回包装后的错误即可。需要注意，path.Match 只匹配单个路径元素的通配规则；复杂的层级模式应按目录层级拆分，或使用专门的遍历策略。

三种场景的选择清单

相关问题

fs.Glob 返回空切片时一定是没有文件吗？

不一定。目录读取失败会被忽略，失败目录下的文件不会出现在结果中；要确认完整性，需要用 WalkDir 等方式记录错误。

怎么判断 Glob 的模式写错了？

检查返回错误是否为 path.ErrBadPattern，不要通过匹配数量判断。模式合法但无匹配时，错误仍然是 nil。

为什么自定义 FS 的 Glob 行为和默认行为不同？

实现 fs.GlobFS 后，标准库会把匹配请求交给该实现，错误和性能策略由实现者定义，调用前应阅读其接口说明。