优先用filepath.WalkDir（Go 1.16+），因其支持精准跳过子目录（return filepath.SkipDir）、避免重复os.Stat、明确处理权限错误，而filepath.Walk易静默终止、跳过不可控且性能差。
直接说结论：别用 filepath.Walk 做“精确控制遍历顺序”或“中途安全中断”的场景——它不支持跳过子目录的优雅方式，错误处理也容易掩盖真实问题；真要可控，优先考虑 filepath.WalkDir（Go 1.16+）。
为什么 filepath.Walk 容易踩坑
它用回调函数 + 全局 error 返回机制，导致两个典型问题：一是遇到权限错误（如 permission denied）时，整个遍历可能静默终止；二是想跳过某个子目录（比如 node_modules），只能靠在回调里 return nil，但这样无法阻止已入栈的子目录被继续访问——底层用的是栈模拟递归，跳过时机不可控。
常见错误现象包括：
- 遍历突然停在某个深层目录，没报错也没日志
- 明明过滤了
.git，结果仍看到它的子文件被传入回调 - 并发调用多个
filepath.Walk时，因共享底层 os.FileInfo 而出现 panic（尤其在 Windows 上）
filepath.WalkDir 怎么用才对
它是 filepath.Walk 的现代替代，返回 fs.DirEntry 而非 os.FileInfo，开销更小，且明确支持跳过子目录：只要在回调中返回 filepath.SkipDir，当前目录下的所有子项立刻被跳过（不是“忽略”，是彻底不入栈）。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
- 始终检查
err是否为filepath.SkipDir，而不是只看nil或非nil - 若需并发安全遍历，自己封装 goroutine + channel，别依赖
WalkDir内部行为 - Windows 下注意路径分隔符，
WalkDir返回的name是相对路径，含\，用filepath.Join拼接时会自动标准化
示例关键片段：
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() && (d.Name() == "node_modules" || d.Name() == ".git") {
return filepath.SkipDir // ✅ 真正跳过
}
if !d.IsDir() {
fmt.Println(path)
}
return nil
})
什么时候该放弃 Walk 系列，手动实现
当需求超出“深度优先、单线程、全路径访问”的范畴时，手动用 os.ReadDir + 递归/队列更可靠。典型场景：
- 需要 BFS（广度优先）遍历（比如找最近一层的
go.mod） - 要限制最大深度（
filepath.Walk不提供深度参数） - 需在遍历中动态修改待访问路径列表（比如根据文件内容决定是否进入某子目录）
- 要求精确的错误分类：区分 “目录不存在”、“读取超时”、“磁盘满” 等不同错误码并分别处理
这种情况下，os.ReadDir 返回的 []fs.DirEntry 更利于控制流，且避免了 Walk 系列隐藏的递归栈管理逻辑。
真正难的不是写遍历逻辑，而是判断「此刻该信任标准库，还是该亲手接管」——尤其当路径里混着符号链接、挂载点、FUSE 文件系统时，WalkDir 的行为边界比文档写的更模糊。
