Go WalkDir 遇到权限错误时怎么记录并继续扫描

用 Go 扫描一棵目录树时，某个子目录没有权限并不一定意味着整次扫描都要失败。filepath.WalkDir 会把访问问题交给回调函数：先记录 path 和 err，再返回 nil，就能放弃当前不可访问路径并继续处理其他兄弟项。真正需要返回错误的，通常是根路径无法打开、记录器写失败，或业务明确要求“有一个错误就终止”的场景。

WalkDir 的错误回调应该怎样处理

filepath.WalkDir(root, fn) 会访问根路径和它能读到的条目。回调签名里的 err 表示当前路径在访问或读取目录时遇到的问题；当它非空时，d 可能不可用，所以不能把 d.IsDir() 放在错误判断之前。

对“记录后继续”的扫描器，错误分支只做两件事：保存问题清单，并返回 nil。这样 WalkDir 不会进入当前出错目录，但仍会继续同级目录。若根路径本身就打不开，WalkDir 最终仍会把这个根级错误返回给调用方，因此要在函数末尾保留一次总错误判断。

package main

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

type walkIssue struct {
    Path string
    Err  error
}

func scan(root string) ([]string, []walkIssue, error) {
    var files []string
    var issues []walkIssue

    walkErr := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        // 先处理访问错误，错误条目不保证可以继续读取 d。
        if err != nil {
            issues = append(issues, walkIssue{Path: path, Err: err})
            if errors.Is(err, fs.ErrPermission) {
                fmt.Printf("权限不足，跳过 %s: %v\\n", path, err)
            }
            // nil 表示放弃当前路径，但继续扫描其他兄弟项。
            return nil
        }

        // 过滤目录要返回 SkipDir，避免进入目录内容。
        if d.IsDir() && d.Name() == ".git" {
            return filepath.SkipDir
        }
        // WalkDir 不递归跟随符号链接，这里显式跳过链接条目。
        if d.Type()&fs.ModeSymlink != 0 {
            return nil
        }
        if !d.IsDir() {
            files = append(files, path)
        }
        return nil
    })
    if walkErr != nil {
        return files, issues, fmt.Errorf("扫描根路径失败: %w", walkErr)
    }
    return files, issues, nil
}

这里的 issues 和 files 分开保存：调用方可以把“扫描成功但有若干不可访问路径”和“根路径级失败”区分开。若业务要求任何错误都中止，把错误分支的 return nil 改成 return err 即可，但这就不再是容错扫描。

过滤目录和符号链接要先判断什么

fs.DirEntry 适合做轻量过滤。Name() 只返回最后一级名称，IsDir() 判断当前条目是否为目录，Type() 返回类型位。优先使用这些信息，只有确实需要大小、权限或时间等完整元数据时，才调用可能再次访问文件系统的 d.Info()，并单独处理它的错误。

目录过滤和符号链接过滤是两个不同判断。目录名匹配时返回 filepath.SkipDir，它表达“不要进入这个目录”；符号链接即使指向目录，也不应被当作普通目录递归。这样可以避免扫描范围被链接指向树意外扩大。

记录错误时的边界清单

如果还要调用 d.Info()，不要把它当成永远成功的属性读取。文件可能在目录读取后被删除或重命名，信息读取失败应再次进入“记录问题还是终止”的业务判断。

相关问题

WalkDir 遇到权限错误为什么不是直接 panic？

权限问题会作为回调参数传入，是否终止由回调返回值决定。只有代码忽略错误并继续解引用无效的 d，才容易出现运行时问题。

返回 filepath.SkipDir 和返回 nil 有什么区别？

SkipDir 明确跳过当前目录的内容；nil 表示当前回调处理完成，正常条目会继续遍历，错误条目则不会被继续进入。

WalkDir 会跟随目录里的软链接吗？

不会。它不跟随目录中发现的符号链接；如果业务需要解析链接目标，应单独调用链接解析逻辑，并设置允许访问的根目录边界。

实际项目里，最稳妥的做法是把“可访问文件列表”“被跳过的问题列表”和“根路径级返回错误”分成三种结果。这样既能尽量完成扫描，也不会把权限缺口伪装成完整成功。