Go filepath.WalkDir按目录深度限制大型仓库扫描范围的实现

大型仓库做文件索引、统计扩展名或查找配置时，直接递归整个目录很容易把 vendor、构建缓存和生成目录一起扫进去。Go 的 filepath.WalkDir 可以在回调里按相对根目录的层级返回 filepath.SkipDir，让超出范围的目录子树立即停止遍历。关键是先处理错误，再计算深度；不能只用字符串前缀判断层级。

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

先用相对路径定义目录深度

WalkDir 回调收到的 path 是从传入根目录拼出的路径。更稳妥的做法是调用 filepath.Rel，再按当前操作系统的分隔符统计层级。根目录本身返回 0，src 是 1，src/pkg 是 2。这样不会因为根目录写成相对路径还是绝对路径而改变口径。

在 WalkDir 回调中返回 filepath.SkipDir

下面的示例只统计最大深度以内的文件。maxDepth 是允许访问的最大层级，不是要跳过的层级；因此判断条件使用 depth > maxDepth。返回 SkipDir 后，当前目录及其后代不会继续回调，已经访问的浅层文件仍会保留。

package main

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

// relativeDepth 把路径转换成相对根目录的层数；根目录固定为 0。
func relativeDepth(root, path string) (int, error) {
    rel, err := filepath.Rel(root, path)
    if err != nil {
        return 0, err // 不同卷或非法路径时交给上层决定是否终止。
    }
    if rel == "." {
        return 0, nil
    }
    return strings.Count(rel, string(os.PathSeparator)) + 1, nil
}

func scan(root string, maxDepth int) error {
    return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return fmt.Errorf("访问 %s 失败: %w", path, err) // d 可能为空，先处理错误。
        }
        depth, err := relativeDepth(root, path)
        if err != nil {
            return err
        }
        if d.IsDir() && depth > maxDepth {
            return filepath.SkipDir // 截断当前目录的整棵子树。
        }
        if !d.IsDir() {
            fmt.Printf("depth=%d file=%s\n", depth, path)
        }
        return nil
    })
}

func main() {
    if err := scan(".", 2); err != nil {
        fmt.Println(err) // 生产代码可替换成带路径的结构化日志。
    }
}

如果 maxDepth 为 2，根目录、一级目录和二级目录仍会被访问；三级目录只会触发一次回调，随后被 SkipDir 截断。文件本身没有可继续深入的子树，即使它的深度大于上限也不应返回 SkipDir，否则会把父目录一并跳过。

处理访问错误、符号链接和跨平台路径

回调的 err 可能来自读取目录或获取条目状态。示例选择直接返回，让一次不可读目录使扫描失败；如果业务允许部分结果，可以记录路径后返回 nil，但要在结果中保留错误计数。不要在 err != nil 前调用 d.IsDir()，否则权限错误可能引发空指针。

WalkDir 默认不跟随符号链接，因此链接目标里的深层内容不会因为深度判断而被扫描。若业务必须追踪链接，应先明确循环链接、越界路径和权限策略，再单独设计解析流程，不能把 EvalSymlinks 直接塞进每次回调。路径分隔符也应交给 filepath 处理，不要写死 /。

用边界清单确认扫描结果

落地前至少确认四件事：扫描根目录是否稳定、最大深度是否从 0 开始计数、被跳过目录是否包含缓存或 vendor、错误是否能在汇总结果中追踪。这样既能减少大型仓库的无效 I/O，也不会把“没有深入符号链接”或“权限不足”误认为深度限制成功。

常见问题

filepath.WalkDir 能否只扫描某个目录名？

可以在回调中先判断 d.IsDir() 和 d.Name()，命中排除目录时返回 filepath.SkipDir；目录名过滤和深度过滤可以叠加。

为什么返回 filepath.SkipDir 后仍然看到了当前目录？

回调会先收到当前目录，SkipDir 只阻止继续进入它的子树，不会撤销已经产生的这次回调。

WalkDir 会自动跟随软链接吗？

不会。它不跟随符号链接；如果要追踪链接，需要额外处理循环、越界和权限风险。

用 filepath.Rel 固定深度口径，再只对目录返回 SkipDir，是限制大型仓库扫描范围的最小可靠方案。