filepath.WalkDir比Walk快得多，因其默认用fs.DirEntry一次读取目录全部条目，IsDir()和Name()零开销不触发stat；而Walk对每个项强制os.Lstat，实测耗时仅Walk的1/3～1/2，但回调中调用d.Info()会抵消该优势。
filepath.WalkDir 为什么比 Walk 快得多
因为 filepath.Walk 对每个目录项都强制调用 os.Lstat，哪怕你只关心文件名；而 filepath.WalkDir 默认用 fs.DirEntry，一次读取整个目录条目，IsDir()、Name() 都是零开销，不触发系统调用。实测在数万小文件场景下，耗时通常只有 Walk 的 1/3～1/2。
但这个优势会被轻易毁掉：只要你在回调里写了 d.Info() 或 os.Stat(path)，就又回到逐个 stat 的老路。性能瓶颈往往不在算法，而在那行多写的 Info()。
- 只判断类型或名字？直接用
d.IsDir()和d.Name() - 真需要大小或修改时间？再调
d.Info()，且记得检查返回的err - 别在循环里拼路径——
filepath.Join(path, d.Name())比path + "/" + d.Name()安全，但仍是热路径瓶颈，高频场景改用strings.Builder缓存父路径
如何安全跳过 .git 和 node_modules
错误做法是用 strings.HasSuffix(path, "/.git") 或 filepath.Base(path) == ".git"：前者会漏掉 .git 目录下的文件（比如 .git/config），后者混淆了路径和文件名语义，还可能误判 my.gitignore 这类文件。
正确逻辑必须结合 d.IsDir() 和 d.Name()，并返回 filepath.SkipDir：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
if err != nil {
if errors.Is(err, os.ErrPermission) {
log.Printf("skip %s: permission denied", path)
return nil
}
return err
}
name := d.Name()
if (name == ".git" || name == "node_modules" || strings.HasPrefix(name, ".")) && d.IsDir() {
return filepath.SkipDir
}
// 其他处理
return nil
})
- Windows 下注意大小写：
.GIT或NODE_MODULES也该过滤，建议统一转小写比较 - 别用
return nil代替filepath.SkipDir——前者只是忽略当前项，子目录仍会被遍历 - 过滤条件放回调开头，避免无谓的后续逻辑执行
遇到 permission denied 时不 panic 的写法
filepath.WalkDir 在进入无权限目录（如 /proc、/root）时，会把 err 设为非 nil，此时 d 是 nil。如果没判空就调 d.Name()，直接 panic。
必须先处理 err，再操作 d：
err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
if err != nil {
// 权限错误：记录后继续，别中断整个遍历
if errors.Is(err, os.ErrPermission) || errors.Is(err, syscall.EACCES) {
log.Printf("permission denied: %s", path)
return nil
}
// 路径被删：常见于并发删除，也应跳过而非终止
if errors.Is(err, os.ErrNotExist) {
return nil
}
return err // 其他错误才中断
}
// 此时 d 一定非 nil，可安全调用 d.Name()、d.IsDir() 等
if d.IsDir() && d.Name() == ".git" {
return filepath.SkipDir
}
return nil
})
- 别用字符串匹配判断错误类型，
errors.Is(err, os.ErrPermission)才可靠 - 返回
nil表示“跳过此项，继续遍历”，不是“成功” - 若需统计跳过数量，单独维护一个计数器，别塞进错误流
想提前退出遍历，别用 fmt.Errorf
filepath.WalkDir 遇到非 nil 返回值就终止。但返回 fmt.Errorf("found %s", path) 这类带上下文的错误，会让上层难以区分是业务命中还是真实 I/O 故障。
推荐定义明确的哨兵错误：
var errFound = errors.New("file found")
// 使用
err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
if err != nil {
if errors.Is(err, os.ErrPermission) {
return nil
}
return err
}
if !d.IsDir() && strings.EqualFold(d.Name(), "config.json") {
*result = path
return errFound // 提前退出
}
return nil
})
if errors.Is(err, errFound) {
// 找到了
} else if err != nil {
// 其他错误
}
- 别用
io.EOF做自定义退出——它有标准语义，容易干扰其他库 - 匹配文件名时用
strings.EqualFold而非==，兼顾 Windows 大小写不敏感 - 想跳过某子树用
filepath.SkipDir，想停整个遍历才用自定义 error
最易被忽略的是：WalkDir 不保证顺序，也不承诺原子性。如果你依赖“第一个匹配即最新”，得额外加排序或时间戳校验——它只负责把路径给你，怎么解释是你的事。
