filepath.Walk 是遍历目录最稳妥的标准库方案，自动处理符号链接、权限错误和循环引用，按深度优先调用回调函数，需正确处理返回的 error（如 filepath.SkipDir）以控制遍历行为。

用 filepath.Walk 遍历目录最稳妥

Go 标准库的 filepath.Walk 是遍历目录的首选，它自动处理符号链接、权限错误、循环引用等边界情况，比手动递归更健壮。

常见错误是忽略回调函数返回的 error —— 如果你在回调里返回非 nil 错误（比如 filepath.SkipDir），Walk 会跳过当前目录的子项；若返回其他错误，则整个遍历终止。

• 回调函数签名必须是 func(path string, info fs.FileInfo, err error) error
• 想跳过某个目录？在回调中返回 filepath.SkipDir
• 遇到权限不足（如 permission denied）时，err != nil 但 info 可能为 nil，需先判空再读 info.IsDir()
• Go 1.16+ 推荐用 fs.WalkDir 替代（见下节），性能更好且不依赖 os.Stat

err := filepath.Walk("/tmp/data", func(path string, info os.FileInfo, err error) error {
    if err != nil {
        if errors.Is(err, os.ErrPermission) {
            return nil // 忽略权限错误，继续
        }
        return err
    }
    if !info.IsDir() {
        fmt.Println("file:", path)
    }
    return nil
})

fs.WalkDir 更快，适合只读场景

fs.WalkDir 是 Go 1.16 引入的替代方案，它使用 ReadDir 而非多次 Stat，避免了大量系统调用，在大目录下性能明显提升。但它不自动解析符号链接目标，也不处理循环软链——这些交由使用者判断。

关键区别：回调接收的是 fs.DirEntry，不是 fs.FileInfo。它轻量，只含名称、是否为目录、是否为符号链接等基本信息；要获取完整信息（如修改时间、大小），得显式调用 entry.Info()（这会触发一次 Stat）。

• 默认不跟随符号链接；若需跟随，得自己用 os.Readlink + filepath.Join 构造新路径并递归
• 不能直接用 filepath.SkipDir；应返回 fs.SkipDir（同类型常量，但属于不同包）
• 如果只需文件名或路径结构（如构建索引），用 DirEntry 就够了，别轻易调 Info()

err := fs.WalkDir(os.DirFS("/tmp/data"), ".", func(path string, d fs.DirEntry, err error) error {
    if err != nil {
        return err
    }
    if !d.IsDir() {
        fmt.Println("file:", path)
    }
    return nil
})

手动递归容易漏掉错误处理和并发控制

有人用 os.ReadDir + for 循环 + 递归函数实现遍历，看似可控，实则隐患多：未处理 io.EOF 或 context.Canceled、没限制 goroutine 数量导致打开过多文件句柄、忽略 Readdir 返回的部分条目（如被其他进程删除）。

尤其要注意：同一目录下大量子目录时，无缓冲 channel 或无限 goroutine 启动会迅速耗尽资源；而 filepath.Walk 和 fs.WalkDir 都是单协程同步执行，天然规避这类问题。

• 若真需要并发（如校验文件哈希），应在回调中启动有限 goroutine，并用 sync.WaitGroup 或 errgroup.Group 控制
• 手动递归时，os.ReadDir 返回的 []fs.DirEntry 不保证顺序，不要假设按字母序
• Windows 下路径分隔符是 \，但 filepath.Walk 和 fs.WalkDir 内部已适配，手动拼接路径务必用 filepath.Join

过滤文件类型或跳过特定路径需在回调里做

标准遍历 API 不提供内置过滤器（比如“只遍历 .go 文件”或“跳过 node_modules”）。所有筛选逻辑必须写在回调函数内部，靠 strings.HasSuffix、filepath.Base、filepath.Ext 或正则匹配完成。

注意：路径字符串是相对还是绝对，取决于你传给 Walk 或 WalkDir 的根路径。例如用 fs.WalkDir(os.DirFS("."), "src", ...)，回调里的 path 是相对于 "src" 的，如 "main.go" 或 "util/helper.go"，不是完整绝对路径。

• 跳过 node_modules 或 .git：检查 filepath.Base(path) == "node_modules" && info.IsDir()，然后返回 filepath.SkipDir 或 fs.SkipDir
• 只处理 .log 文件：if filepath.Ext(path) == ".log" && !info.IsDir()
• 避免重复计算：提前用 filepath.Ext 或 strings.TrimPrefix 提取后缀，别在每次回调都用正则