遍历目录时跳过无权限分支并汇总可读文件

Go 遍历目录时，如果希望“某个子目录没权限就跳过，但其他分支继续统计”，关键不是在外层捕获 filepath.WalkDir 的最终错误，而是在 WalkDirFunc 回调里处理传入的 err：根目录本身不可访问时返回错误；子目录遇到 fs.ErrPermission 时记录一次并返回 fs.SkipDir；普通文件则实际打开一次，成功后立即关闭并累计数量与字节数。

官方文档：https://pkg.go.dev/path/filepath#WalkDir

WalkDir 负责发现条目，fs.SkipDir 负责跳过目录分支，os.Open 才能确认当前进程在扫描这一刻是否真的能打开文件。只检查权限位不能覆盖 ACL、进程身份和平台差异。

WalkDirFunc 把错误处理权交给回调

filepath.WalkDir 从根目录开始访问每个文件和目录。访问过程中产生的错误不会自动采用固定策略，而是作为回调的 err 参数交给调用方决定。回调返回值的含义如下：

当目录的 ReadDir 失败时，回调会再次收到这个目录，并带着非空 err。此时 d 仍描述该目录，所以可以安全判断 d.IsDir() 后返回 fs.SkipDir。如果根目录最初的状态读取就失败，d 可能为 nil，不能直接调用它的方法。

为什么优先使用 WalkDir 而不是旧 Walk

filepath.WalkDir 从 Go 1.16 起提供 fs.DirEntry 回调。与旧的 filepath.Walk 相比，它不必为每个访问到的条目都额外调用 os.Lstat，因此只需要名称和类型时更省系统调用。不过，本文要确认“文件可读”，仍需要对常规文件主动调用 os.Open。

WalkDir 会按字典序遍历，这让相同目录内容得到稳定顺序，但代价是进入某个目录前要把该目录的条目整体读入内存。单个目录包含海量文件时，这一点比总文件数更值得关注。

最小完整实现

下面的实现只跳过非根目录中的权限错误。其他目录读取错误继续向上返回，避免磁盘 I/O 故障被误报成“扫描成功”。错误路径只保留少量样本，计数仍完整，防止异常目录过多时报告本身占用大量内存。

package scan

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

const maxSamples = 8

type Report struct {
    Files               int
    Bytes               int64
    SkippedDirs         int
    UnreadableFiles     int
    SkippedDirSamples   []string
    UnreadableSamples   []string
}

func addSample(items []string, path string) []string {
    // 只保留有限样本，完整数量由计数字段承担
    if len(items) 

代码没有读取文件内容，因此“可读”在这里表示扫描时可以成功打开常规文件，而不是保证后续完整读取永远成功。文件可能在扫描后被删除、替换或修改，统计是一个时间点快照。

调用方式与结果判断

package main

import (
    "fmt"
    "log"

    "example.com/project/scan"
)

func main() {
    // 将目标根目录替换为当前任务需要扫描的位置
    report, err := scan.SummarizeReadable("./data")
    if err != nil {
        log.Fatal(err)
    }

    // 只打印汇总与有限样本，避免大目录产生海量日志
    fmt.Printf("可读文件=%d 字节=%d 跳过目录=%d 不可读文件=%d\n",
        report.Files, report.Bytes, report.SkippedDirs, report.UnreadableFiles)
    fmt.Printf("跳过目录样本=%v\n", report.SkippedDirSamples)
    fmt.Printf("不可读文件样本=%v\n", report.UnreadableSamples)
}

验收时应准备三个独立区域：一个正常目录、一个当前进程无权读取的子目录、一个无法打开的常规文件。预期判断是正常目录继续进入，无权限子目录只增加 SkippedDirs，不可读文件只增加 UnreadableFiles，而根目录无权限则返回非空错误。本文不把示例输出写成固定数字，因为权限受运行账户、ACL 和操作系统影响。

性能与边界条件

若只想汇总“目录项看起来是常规文件”的数量，可以省略 os.Open，速度会更快，但不能再称为当前进程可读。需要真实可读性时，逐文件打开无法凭权限位完全替代。可以通过以下方式控制成本：

• 文件打开后立即关闭，任何时刻只持有一个额外描述符；
• 错误样本设上限，计数与样本分离；
• 先按扩展名、目录或大小需求过滤，再做打开检查；
• 不要在回调里无上限启动 goroutine；WalkDir 本身是顺序遍历，盲目并发会放大文件描述符压力；
• 默认不跟随目录中发现的符号链接，避免把链接目标意外计入当前树。

如果业务确实需要并发打开，可让回调只收集有限任务并发送到固定大小的 worker 池，同时设置背压与最大打开文件数。这已经属于另一层资源调度，不应改变 WalkDir 的错误语义。

常见问题

遇到任何目录错误都返回 fs.SkipDir 可以吗？

不建议。权限不足可以按业务规则跳过，但介质错误、路径损坏或其他 I/O 故障可能意味着统计不完整。至少用 errors.Is(err, fs.ErrPermission) 区分，再决定是否容忍。

为什么不能通过 0644 判断文件可读？

权限位只是判断依据之一。实际结果还受进程 UID/GID、ACL、Windows 权限模型、挂载选项和文件系统行为影响。打开文件才是当前进程最直接的检查。

返回 fs.SkipDir 时 d 可能为 nil 吗？

根目录初始状态读取失败时可能为 nil，因此要先处理 d == nil。目录读取阶段失败时，回调会带着描述该目录的 DirEntry 再调用一次，这时才能安全判断 d.IsDir()。

WalkDir 会进入符号链接目录吗？

filepath.WalkDir 不跟随遍历中发现的符号链接。本文也显式跳过链接，避免后续 os.Open 跟随目标后把目录树之外的文件计入统计。