Go WalkDir 怎样按文件名模式筛选条目

我在做目录索引时，最容易写错的地方不是 fs.WalkDir 本身，而是把“文件名筛选”和“路径筛选”混成一件事。WalkDir 回调拿到的是文件系统中的逻辑路径，例如 assets/css/site.css；如果需求是“只要所有目录下名字符合 *.css 的文件”，应先取出最后一段，再交给 path.Match。官方地址：https://pkg.go.dev/io/fs#WalkDir

按文件名筛选的稳定写法是：在 WalkDir 回调里先处理错误，再用 d.IsDir() 跳过目录，使用 path.Base(path) 取得文件名，最后调用 path.Match。匹配失败不是错误；模式语法错误则必须单独处理 path.ErrBadPattern。

先把筛选目标说清楚：文件名还是完整路径

path.Match(pattern, name) 要求模式匹配整个 name，不是在字符串中查找一段子串。对 assets/css/site.css 直接使用 *.css，不会因为最后一段是 site.css 就自动成功；如果目标是文件名，应先调用 path.Base。如果目标是固定目录下的文件，则可以保留完整逻辑路径，并把目录层级写进模式。

这个区分也影响指标。以文件名匹配为例，docs/readme.md 和 archive/readme.md 都会命中 readme.md；以完整路径匹配为例，模式可以只允许 docs/*.md。先确定业务边界，再决定送入匹配器的字符串，排查起来会比盲目调整通配符快很多。

在 WalkDir 回调里先处理目录和访问错误

回调参数中的 err 代表访问当前路径时遇到的问题，不能直接忽略。目录和文件都可能先经过回调，因此要先判断错误，再判断 d.IsDir()。不匹配的普通文件应该返回 nil，这样遍历仍会继续；只有明确需要剪枝或停止时，才返回 fs.SkipDir 或 fs.SkipAll。

package main

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

// matchFiles 只收集名字符合 pattern 的普通文件。
func matchFiles(files fs.FS, pattern string) ([]string, error) {
    result := make([]string, 0)

    err := fs.WalkDir(files, ".", func(name string, entry fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            // 访问错误要交给上层决定，不能把缺失目录伪装成“没有匹配项”。
            return walkErr
        }
        if entry.IsDir() {
            // 目录本身不是待收集文件；返回 nil 表示继续进入其子项。
            return nil
        }

        fileName := path.Base(name)
        matched, err := path.Match(pattern, fileName)
        if err != nil {
            // 模式写错属于配置错误，保留原错误让调用方修正模式。
            return fmt.Errorf("文件名模式 %q 无效: %w", pattern, err)
        }
        if matched {
            result = append(result, name)
        }
        // 未命中的文件不是遍历错误，继续访问后续条目。
        return nil
    })
    if err != nil {
        return nil, fmt.Errorf("遍历文件系统失败: %w", err)
    }
    return result, nil
}

上面的函数只依赖 fs.FS，所以可以接收 os.DirFS、嵌入文件系统或测试用的内存文件系统。返回结果中的路径仍是 fs.FS 语义下的斜杠路径，不应直接当成当前操作系统的绝对路径。

为什么要用 path.Base，而不是手写字符串截取

io/fs 的逻辑路径统一使用正斜杠，path.Base 正好按这种路径规则取最后一个元素。手写 strings.Split 或按操作系统分隔符切割，容易遗漏根路径、连续分隔符和跨平台输入的边界，也会让“路径规则”和“文件名规则”混在一起。

func matchesFileName(logicalPath, pattern string) (bool, error) {
    // WalkDir 返回的是 slash-separated 的逻辑路径，使用 path 而非 filepath。
    baseName := path.Base(logicalPath)
    matched, err := path.Match(pattern, baseName)
    if err != nil {
        // ErrBadPattern 表示模式语法错误，不代表当前文件没有命中。
        return false, fmt.Errorf("匹配 %q: %w", logicalPath, err)
    }
    return matched, nil
}

例如，模式 report-??.csv 会匹配 report-01.csv，但不会匹配 report-1.csv；模式 *.csv 只对传入的完整文件名做匹配。它不是正则表达式，不能把 +、捕获组或惰性量词直接搬过来。

模式错误、访问错误和不匹配要分三类

这三种情况在日志里最好使用不同的描述：

把合法但未命中的文件记录为 error，会让监控产生大量噪声；把模式语法错误当成普通未命中，则会让调用方误以为目录里没有目标文件。分别处理后，基线数据才有意义。

不匹配时该继续、剪枝还是停止

“不符合文件名模式”通常只影响当前文件，因此返回 nil。如果某个目录整体都不需要扫描，例如明确排除 vendor，应在目录分支判断目录名后返回 fs.SkipDir；它表示跳过当前目录及其子树。fs.SkipAll 则用于满足结果后提前结束整个遍历，不能把它当成普通过滤结果。

func collectGoFiles(files fs.FS) ([]string, error) {
    var matches []string
    err := fs.WalkDir(files, ".", func(name string, entry fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            // 当前节点不可访问时停止，调用方可以按需改为记录后继续。
            return walkErr
        }
        if entry.IsDir() {
            if path.Base(name) == "vendor" {
                // vendor 目录不属于本次索引范围，只剪枝这一棵子树。
                return fs.SkipDir
            }
            return nil
        }

        matched, err := path.Match("*.go", path.Base(name))
        if err != nil {
            // 常量模式也保留错误分支，便于以后改成配置时不改变语义。
            return err
        }
        if matched {
            matches = append(matches, name)
        }
        return nil
    })
    return matches, err
}

用几个简单指标判断筛选是否值得保留

风格上我更建议先记录一次基线，再谈优化。对同一个文件系统，统计访问条目数、命中文件数、剪枝目录数和模式错误数即可。WalkDir 按词典序访问目录，输出顺序稳定；但它仍然要访问到回调能看到的条目，文件名过滤不会神奇地让底层目录读取变成索引查询。

type ScanStats struct {
    Visited  int
    Matched  int
    Pruned   int
    BadMatch int
}

// scanWithStats 让筛选结果和遍历成本可以一起观察。
func scanWithStats(files fs.FS, pattern string) (ScanStats, error) {
    var stats ScanStats
    err := fs.WalkDir(files, ".", func(name string, entry fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            return walkErr
        }
        stats.Visited++
        if entry.IsDir() {
            return nil
        }
        matched, err := path.Match(pattern, path.Base(name))
        if err != nil {
            stats.BadMatch++
            return err
        }
        if matched {
            stats.Matched++
        }
        return nil
    })
    return stats, err
}

如果 Visited 很大而 Matched 很小，说明“先遍历再按名字过滤”可能不是合适的整体方案，可以考虑更窄的根目录、fs.SkipDir 剪枝，或使用已有索引。这个判断依赖自己的目录结构和访问成本，不能只凭通配符写法下结论。

常见问题

path.Match("*.go", "cmd/main.go") 为什么不匹配？

因为传入值包含目录分隔符且模式要求完整匹配。要匹配任意目录下的 Go 文件，先对逻辑路径调用 path.Base。

可以用 filepath.Match 吗？

如果处理的是 fs.WalkDir 返回的逻辑路径，优先使用 path.Match，因为 io/fs 约定使用正斜杠。只有在已经明确转换成操作系统本地路径时，才考虑 filepath.Match。

遇到不匹配目录应该返回 fs.SkipDir 吗？

只有当目录及其全部子树都不在目标范围内时才剪枝。单纯因为目录名本身不符合文件模式，并不代表里面的文件都不需要检查。

怎样提前停止找到的第一个文件？

可以在命中后返回 fs.SkipAll，但要明确这会终止剩余遍历；如果只是跳过当前目录，则使用 fs.SkipDir。

小结

Go 用 fs.WalkDir 做文件名模式筛选时，关键顺序是：先处理访问错误，再区分目录与文件；文件名筛选取 path.Base，完整路径筛选则保留逻辑路径；用 path.Match 做完整模式匹配，并把 ErrBadPattern 与普通未命中分开。最后再根据实际访问统计决定是否需要目录剪枝或更专门的索引。