Go 怎样遍历目录并跳过指定子树

Go 遍历目录并跳过指定子树，最直接的写法是使用 filepath.WalkDir，在回调里先判断当前项是不是目标目录，命中后返回 filepath.SkipDir。这个返回值只跳过当前目录及其后代，不会结束整个遍历；普通文件则继续返回 nil。

官方文档：https://pkg.go.dev/path/filepath#WalkDir

如果还要记录文件、过滤扩展名或处理权限错误，可以把“是否跳过目录”和“是否返回真实错误”分开写。这样目录树较大、存在多个同名目录时，行为也更容易解释。

先分清三个遍历选择

本地磁盘路径通常选择 filepath.WalkDir；如果代码面对的是 embed.FS、os.DirFS 或其他实现了 io/fs.FS 的抽象文件系统，则选择 io/fs.WalkDir。两者都接收回调、都能返回 SkipDir，但路径格式和回调参数来源不同。

最小写法：命中目录就跳过整棵子树

下面的例子只排除名为 vendor 的目录，同时收集其他目录中的 Go 文件。d.IsDir() 放在名字判断前面，避免同名文件被误当成待跳过的子树。

package main

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

func listGoFiles(root string) ([]string, error) {
    var files []string

    err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        // 访问目录或文件失败时，保留路径上下文并停止本次遍历。
        if err != nil {
            return fmt.Errorf("访问 %s: %w", path, err)
        }
        // 只有目录才能代表一棵子树；同名普通文件不应被跳过。
        if d.IsDir() && d.Name() == "vendor" {
            return filepath.SkipDir
        }
        // 只收集普通 Go 文件，目录和其他扩展名继续遍历但不入结果。
        if !d.IsDir() && filepath.Ext(d.Name()) == ".go" {
            files = append(files, path)
        }
        return nil
    })
    if err != nil {
        return nil, err
    }
    return files, nil
}

func main() {
    // 根目录来自调用方；这里不把真实机器路径写死在示例中。
    files, err := listGoFiles(".")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(files)
}

关键点只有两个：回调被调用到 vendor 这一项时，返回 filepath.SkipDir；遍历器收到这个特殊值后不会再进入它的子项，随后继续处理同级目录。回调已经访问到的目录项仍然算作“遇到过”，但其后代不会进入回调。

filepath.WalkDir 会把根目录本身也交给回调。若根目录恰好就叫 vendor，上面的规则会直接跳过根目录内容；这通常是符合“排除该目录树”的定义，但如果根目录不能被跳过，就要在条件里先排除根路径。

目录名匹配与路径匹配怎么选

按 d.Name() 判断适合“所有层级中名为 vendor 的目录都排除”。如果只想跳过根目录下的 cache/vendor，就使用 filepath.Rel 得到相对路径，或用清晰的路径比较，不要只用字符串前缀。

func shouldSkip(root, path string, d fs.DirEntry) (bool, error) {
    // 文件不可能代表子树，因此先返回 false，避免误伤同名文件。
    if !d.IsDir() {
        return false, nil
    }
    rel, err := filepath.Rel(root, path)
    if err != nil {
        return false, fmt.Errorf("计算相对路径: %w", err)
    }
    // 只跳过明确的缓存目录，不把 cache-backup 等相似名称算进去。
    return rel == filepath.Join("cache", "vendor"), nil
}

如果需要对多个固定子树做判断，可以把规范化后的相对路径放进集合；如果只按最后一级目录名判断，直接使用 d.Name() 更短。不要用 strings.HasPrefix(path, "./cache") 代替边界判断，因为 ./cache-old 也可能被错误匹配。

SkipDir、SkipAll 和普通错误不是一回事

filepath.SkipDir 是局部跳过，io/fs.SkipAll 是终止剩余遍历，其他非 nil 错误通常会让 WalkDir 停止并返回该错误。目录排除规则不要返回普通错误，否则调用方会把“主动忽略”误记成“遍历失败”。

回调的 err 表示当前路径访问遇到了问题。这时 d 可能为空，因此要先处理 err，再调用 d.IsDir() 或 d.Name()。如果业务允许忽略某类权限错误，也要明确记录并返回 nil；不要无条件吞掉错误。

几个容易误判的边界

• 不会跟随目录内的符号链接。filepath.WalkDir 默认不进入目录中的符号链接目标；不要把“跳过子树”理解成已经完成了链接解析安全控制。
• 遍历顺序是字典序。它适合需要稳定输出的工具，但大目录读取和排序仍然有内存成本，不应把顺序当成业务优先级。
• SkipDir 不是跳过当前文件。对目录返回它会跳过目录内容；对文件返回它的语义会影响所在目录的剩余项，文件过滤通常不要返回这个值。
• 本地路径与 FS 路径不要混用。filepath.WalkDir 使用操作系统分隔符，而 io/fs.WalkDir 使用斜杠分隔的抽象路径。
• 不要把输出顺序当成并发结果。如果后续把文件处理改成并发，遍历顺序与处理完成顺序应分别建模。

按场景做一个小决策

因此，题目中的“跳过指定子树”可以固定成一条规则：先确认回调没有错误，再确认当前项是目录，最后根据目录名或相对路径返回 filepath.SkipDir。只有真正需要停止整个任务时，才考虑 SkipAll 或返回普通错误。

常见问题

可以用 filepath.SkipDir 跳过某个文件吗？

不建议。它是目录遍历控制信号，返回时应优先确认 d.IsDir()。文件过滤直接返回 nil，由回调决定是否收集即可。

多个同名目录都要跳过怎么办？

使用 d.IsDir() && d.Name() == "vendor"，它会对每一层同名目录生效。如果只排除一个固定位置，改用相对路径匹配。

为什么回调里 d 可能为空？

当根路径或某个目录项的访问发生错误时，回调会收到非空 err，此时不能假设 d 可用。先返回或按业务处理错误，再访问目录项。

记住“目录判断决定是否 SkipDir，错误判断决定是否继续，遍历对象决定选 filepath 还是 io/fs”，就能覆盖大多数 Go 目录排除需求。