WalkDir遇到权限错误应继续还是退出

我在做目录索引时遇到过一个很容易被忽略的现象：filepath.WalkDir 走到一个没有读取权限的目录，回调收到了错误，但程序到底应该继续、跳过，还是直接失败，并没有一个对所有业务都正确的答案。

判断标准很简单：允许结果不完整的批量扫描，记录权限错误后返回 nil；只想放弃当前受限目录，返回 fs.SkipDir；要求结果完整可审计，返回原始 err 让 WalkDir 结束。根路径本身无法访问时，则不存在真正的“继续遍历”，应该把它当成一次失败或明确的空结果。

资料入口：https://pkg.go.dev/path/filepath

先看权限错误发生在哪一层

filepath.WalkDir 从根路径开始遍历，并把访问过程中的错误交给 fs.WalkDirFunc。根路径的初始 Stat 失败时，回调收到的 d 是 nil，此时没有任何子目录可以继续走。子目录已经被父目录读到，但真正读取它的内容失败时，回调通常会再次收到这个目录对应的 DirEntry，并带上 ReadDir 返回的错误。

这个差异决定了回调不能只写一行 if err != nil { return nil }。它可能把“根路径完全不可用”伪装成成功，也可能把一个应该阻断的非权限错误吞掉。

三种返回值对应三种业务结果

返回值不是代码风格问题，而是扫描结果的契约：

对于目录读取失败，fs.SkipDir 的语义最清楚：当前目录已经无法读取，跳过它，但不影响同级目录。对于根路径错误，即使返回 fs.SkipDir，WalkDir 也只会结束本次调用，不会神奇地找到另一棵树。

把权限错误和其他错误分开

工程代码里更稳妥的做法是用 errors.Is 判断 fs.ErrPermission，而不是匹配错误字符串。这样可以兼容底层返回的 *os.PathError 包装。权限错误可以按业务策略降级，路径损坏、I/O 错误或其他不可预期错误则继续向上返回。

package main

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

// walkReadableTree 扫描可访问目录；权限不足时保留部分结果，其他错误仍然失败。
func walkReadableTree(root string) error {
    return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            // 根路径 Stat 失败时 d 为 nil，继续并不代表扫描成功。
            if d == nil {
                return fmt.Errorf("无法访问扫描根路径 %q: %w", path, err)
            }

            if errors.Is(err, fs.ErrPermission) {
                // 当前目录内容读不到，保留同级目录的扫描机会。
                fmt.Printf("跳过无权限目录: %s\\n", path)
                return fs.SkipDir
            }

            // 非权限错误可能意味着存储或路径异常，不要静默吞掉。
            return err
        }

        // 这里只处理已成功读取的条目；目录是否继续由 WalkDir 管理。
        fmt.Println(path)
        return nil
    })
}

这段回调选择了“部分结果可用”的策略：根路径失败直接报错，子目录权限错误跳过，其他错误终止。若业务允许把权限问题也当作普通缺口，只需把 return fs.SkipDir 改成记录后 return nil；但要在返回结果中保留“存在未扫描目录”的状态。

为什么有时会看到同一个目录回调两次

WalkDir 在准备读取目录前会先调用一次回调，让程序有机会提前返回 fs.SkipDir 或 fs.SkipAll。如果随后 ReadDir 失败，它会再次为同一路径报告错误。因而日志里出现同一个目录先是 err == nil、后来才是权限错误，并不代表重复扫描了两遍。

如果日志需要统计“真正发生的权限失败”，应只在 err != nil 的分支计数；如果要记录访问意图，则可以同时记录第一次回调。不要用回调次数直接当作目录数量。

我现在会怎样选择继续还是退出

我的判断顺序是先问结果能不能不完整，再问错误能不能恢复：

1. 目录搜索、文件名提示、缓存索引：权限错误记录为警告，优先返回 nil 或 fs.SkipDir，让可访问内容继续产出。
2. 备份、合规盘点、迁移前清点：任何权限缺口都应返回原始错误，同时把失败路径写入报告，避免把“部分成功”当成“全量完成”。
3. 根路径失败：不把返回 nil 当成成功；至少向上返回带路径上下文的错误，或由调用方明确把它标记为“无结果”。
4. 非权限错误：默认退出。只有业务明确允许降级时，才为某一类错误设计单独的忽略规则。

最后复查三个信号：调用返回值是否被处理、是否记录了被跳过的路径、最终状态是否区分“完整”“部分”和“失败”。这三项比单纯看到程序没有崩溃更能说明 WalkDir 的处理是正确的。

相关问题

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

filepath.WalkDir 默认不跟随目录中的符号链接。若任务需要处理链接目标，应先单独定义安全边界和循环处理策略，不要因为权限错误就顺手改成递归跟随。

什么时候用 fs.SkipAll？

当已经得到足够结果，或发现继续遍历没有业务价值时可以使用。它表示跳过剩余全部文件和目录，语义比 fs.SkipDir 更强。

为什么不建议比较“permission denied”字符串？

错误通常会被路径错误包装，且不同操作系统的文本可能不同。使用 errors.Is(err, fs.ErrPermission) 更稳定，也更符合 Go 的错误链设计。