Go WalkDir 遇权限目录怎样继续遍历

用 filepath.WalkDir 扫描目录时，遇到一个没有访问权限的子目录，不一定要让整棵目录树失败。关键是先处理回调里的 err，再决定返回 nil、fs.SkipDir、fs.SkipAll 还是原始错误。对“当前子目录不可读、但兄弟路径仍要继续”的场景，通常在确认是 fs.ErrPermission 后记录路径并返回 nil。

不要无条件调用 d.IsDir()：根目录的初始 Stat 失败时，回调中的 d 可能是 nil。正确的判断顺序是先看 err，用 errors.Is 识别权限错误，再按业务决定局部跳过、全部停止或继续上抛。

• 继续兄弟路径：当前访问错误已被记录且允许降级时，返回 nil。
• 主动跳过目录：已知某个目录不应进入时，返回 fs.SkipDir。
• 立即停止：返回 fs.SkipAll 或其他非 nil 错误。

先看 WalkDir 回调中的 err 与 d

filepath.WalkDir 会把根路径和每个访问到的文件或目录交给 fs.WalkDirFunc。回调签名中的 path 是当前路径，d 是对应的 fs.DirEntry，err 则表示访问该路径时发生的错误。

官方文档规定了两个容易混淆的情况：

• 如果根目录的初始 Stat 失败，回调会收到根路径、d == nil 和非空错误。
• 如果读取某个目录失败，回调会再次收到这个目录的路径和错误；这时 d 可以描述该目录。

所以回调的第一行应该处理错误，而不是先写 d.IsDir()。只要把 err 和 d 看成两条独立信息，权限目录的处理就不会因为空指针或错误分支混乱。

用 errors.Is 识别权限错误

文件系统通常会把底层错误包在 *fs.PathError 中。直接比较 err == fs.ErrPermission 很容易漏掉包装后的情况，应使用 errors.Is(err, fs.ErrPermission)。这样只对明确的权限错误做降级，其他磁盘、挂载或 I/O 错误仍能保持可见。

package main

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

func collectReadable(root string) (files []string, skipped []string, err error) {
    err = filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
        // 先处理访问错误，避免在根目录 Stat 失败时调用空 d 的方法。
        if walkErr != nil {
            if errors.Is(walkErr, fs.ErrPermission) {
                // 当前路径不可读，但允许继续处理其他兄弟路径。
                skipped = append(skipped, path)
                return nil
            }
            // 非权限错误保留路径上下文，交给调用方决定是否终止。
            return fmt.Errorf("访问 %s 失败: %w", path, walkErr)
        }

        // err 为空时，正常的 WalkDir 回调应当提供目录项。
        if d == nil {
            return fmt.Errorf("访问 %s 时缺少目录项", path)
        }
        if !d.IsDir() {
            files = append(files, path)
        }
        return nil
    })
    return files, skipped, err
}

这个函数的语义是“尽量收集可读文件，同时返回被跳过的路径”。注意它没有把所有错误都转换成“继续”：只有 fs.ErrPermission 被记录后忽略，其他错误仍然返回。根目录本身无权限时也会进入权限分支；如果业务要求根目录不可读必须失败，可以在 path == root 时改为返回原错误。

让权限目录跳过后继续兄弟路径

权限错误已经发生时，返回 nil 的含义是“不把这个回调错误继续上抛”。WalkDir 已经知道当前路径无法继续向下读取，因此会回到遍历逻辑，继续处理其他可访问的路径。这个写法适合备份索引、文件清单和搜索类工具：结果允许不完整，但必须把跳过项记录下来。

如果目录是否进入可以在回调第一次到达时根据路径规则确定，则可以在尚未读取目录之前主动返回 fs.SkipDir：

package main

import (
    "io/fs"
    "path/filepath"
    "strings"
)

func walkWithoutCache(root string) error {
    return filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
        // 已经发生的错误先交给上层，不把所有失败都误判成权限问题。
        if walkErr != nil {
            return walkErr
        }

        // 目录规则已知时提前跳过，避免进入目录读取更多条目。
        if d != nil && d.IsDir() && strings.HasSuffix(path, ".cache") {
            return fs.SkipDir
        }
        return nil
    })
}

这里的 fs.SkipDir 是主动的目录策略，不是“忽略权限错误”的替代品。对已经报告了读取错误的回调，尤其是根目录 d == nil 的情况，不要为了看起来统一而无条件返回 fs.SkipDir。

区分 SkipDir、SkipAll 和真正失败

这几个返回值的作用范围不同，混用会让调用方误以为“完整扫描”已经成功：

官方定义中，fs.SkipDir 的语义是跳过当前目录；当回调对应的是文件时，它会跳过该文件的父目录。fs.SkipAll 则跳过全部剩余项。两者都不是普通的业务错误，调用方如果需要知道“扫描是否完整”，仍应通过独立统计或最终返回值表达。

把错误记录和结果统计放在遍历边界

一个实用的边界是让回调只负责三件事：识别错误、更新跳过记录、返回遍历控制信号；让外层函数负责汇总文件数量和最终错误。这样调用者可以选择“允许部分结果”或“部分结果也算失败”，不会把策略散落到每个文件处理分支。

package main

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

type WalkReport struct {
    Files   int
    Skipped []string
}

func scan(root string, stopOnPermission bool) (WalkReport, error) {
    var report WalkReport
    err := filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
        // 权限策略由调用方选择：容忍则继续，严格模式则停止全部遍历。
        if walkErr != nil {
            if errors.Is(walkErr, fs.ErrPermission) {
                report.Skipped = append(report.Skipped, path)
                if stopOnPermission {
                    return fs.SkipAll
                }
                return nil
            }
            return fmt.Errorf("遍历 %s 失败: %w", path, walkErr)
        }
        if d == nil {
            return fmt.Errorf("遍历 %s 时目录项为空", path)
        }
        if !d.IsDir() {
            report.Files++
        }
        return nil
    })
    return report, err
}

在宽松模式下，report.Skipped 让上层知道结果存在缺口；在严格模式下，遇到第一个权限错误就返回 fs.SkipAll，外层仍需要结合报告判断这是“主动停止”还是“完整成功”。如果权限错误本身必须作为失败原因传递，直接返回带路径上下文的错误会更明确。

发布前可以按这张表复查

1. 回调第一步是否先判断 err，并在 d == nil 时避免调用方法。
2. 权限判断是否使用 errors.Is，而不是只比较错误字符串。
3. 想继续兄弟路径时是否返回 nil，想跳过已知目录时是否返回 fs.SkipDir。
4. 是否明确区分 fs.SkipAll 与其他非 nil 错误的停止语义。
5. 是否记录跳过路径，让“扫描完成”与“扫描完整”不被混为一谈。

常见问题

遇到权限目录返回 nil 后，WalkDir 会继续吗？

对于回调收到的当前访问错误，返回 nil 表示不把该错误继续上抛；WalkDir 不会进入这个不可读目录，并会继续处理其他路径。是否接受不完整结果，要由外层报告决定。

可以用 fs.SkipDir 忽略权限错误吗？

不要无条件这样做。fs.SkipDir 更适合已知的目录过滤规则；处理权限错误时先检查 d 和 err，根目录错误可能没有可用的 d。

errors.Is 能识别被 PathError 包装的权限错误吗？

可以。文件系统错误通常带有路径上下文，使用 errors.Is(err, fs.ErrPermission) 能沿包装链判断底层是否为权限错误。

什么时候应该返回真正的非 nil 错误？

当目录清单必须完整、错误可能表示磁盘或挂载故障，或者调用方需要触发重试时，应保留错误并停止遍历，而不是把所有失败都当成可跳过目录。

官方 API 参考：https://pkg.go.dev/path/filepath#WalkDir、https://pkg.go.dev/io/fs#WalkDirFunc、https://pkg.go.dev/io/fs#SkipDir、https://pkg.go.dev/io/fs#SkipAll、https://pkg.go.dev/io/fs#ErrPermission、https://pkg.go.dev/errors#Is。