Go filepath.WalkDir 怎样处理空值和异常分支

Go filepath.WalkDir 的回调应先检查 walkErr，再调用 d.IsDir、d.Name 等方法。根路径无法取得条目时，d 可能为 nil；遇错直接解引用会把一个普通文件访问错误变成 panic。处理完回调错误后，外层还要接住 WalkDir 的返回值，避免失败被忽略。

Go 官方地址：https://go.dev/。下面先给出适合放入已有扫描函数的回调骨架，再给一份带部分结果标记的完整命令行程序。

先处理 walkErr，再访问目录条目

// 错误分支必须位于条目访问之前，保留底层错误供调用者判断。
err := filepath.WalkDir(root, func(name string, d fs.DirEntry, walkErr error) error {
    if walkErr != nil {
        return fmt.Errorf("访问 %q: %w", name, walkErr)
    }
    // 正常标准库回调中，此时应有条目；防御性检查便于复用回调。
    if d == nil {
        return fmt.Errorf("路径 %q 缺少目录条目", name)
    }
    if d.IsDir() {
        return nil
    }
    return nil
})
// 外层也必须处理返回值，否则回调错误仍然会丢失。
if err != nil {
    return err
}

这个骨架选择遇错停止。它展示的是回调核心片段，root 以及 fmt、io/fs、path/filepath 由所在函数提供；下文的完整程序包含所需导入和命令行入口。

nil 条目与空目录是不同概念。空目录依然有目录条目，只是没有子项；nil 表示本次回调没有可用条目，应该结合 walkErr 处理。也不应给 nil 临时补造一个“空条目”再继续统计。

把生产目标写成明确的错误政策

只读扫描也需要约定完成标准。本例的目标是统计普通文件条目，主动排除根目录之下名为 .git 的目录；根路径必须是目录。由于子目录权限问题而遗漏的区域必须记入警告，不能静默算作扫描完成。

这不是标准库强制的容错政策。如果业务要求目录一个也不能漏，可以删掉权限容忍分支，统一返回错误；如果只是交互式浏览，则可能更重视尽量展示结果。关键是政策和最终状态一致。

用完整程序报告部分结果

以下 main.go 仅查询目录条目，不更改权限、不删除文件、不打开文件正文。它把统计和退出状态放在不同层：collect 收集结果，run 负责报告，调用方据退出码判断是否完整。

package main

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

type Report struct {
    Files    int
    Excluded int
    Warnings []string
}

func collect(root string) (Report, error) {
    r := Report{}
    // 空配置不能被 Clean 隐式变成当前目录。
    if root == "" {
        return r, fmt.Errorf("根目录不能为空")
    }
    root = filepath.Clean(root)
    err := filepath.WalkDir(root, func(name string, d fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            // 根失败或条目缺失时，不继续用 d，也不把结果当作空目录。
            if name == root || d == nil {
                return fmt.Errorf("访问根或缺失条目 %q: %w", name, walkErr)
            }
            // 只有已知的子目录权限错误才按政策跳过；其他错误终止。
            if d.IsDir() && errors.Is(walkErr, fs.ErrPermission) {
                r.Warnings = append(r.Warnings,
                    fmt.Sprintf("子目录未完整扫描 %q: %v", name, walkErr))
                return fs.SkipDir
            }
            return fmt.Errorf("访问 %q: %w", name, walkErr)
        }
        if d == nil {
            return fmt.Errorf("路径 %q 缺少目录条目", name)
        }
        if name == root && !d.IsDir() {
            return fmt.Errorf("指定根路径不是目录")
        }
        if d.IsDir() {
            // 只对目录返回 SkipDir；主动排除与权限遗漏分开统计。
            if name != root && d.Name() == ".git" {
                r.Excluded++
                return fs.SkipDir
            }
            return nil
        }
        // 这里只统计条目类型所示的普通文件，不打开正文。
        if d.Type().IsRegular() {
            r.Files++
        }
        return nil
    })
    return r, err
}

func run(args []string) int {
    if len(args) != 1 || args[0] == "" {
        fmt.Fprintln(os.Stderr, "用法: walkreport ROOT")
        return 2
    }
    r, err := collect(args[0])
    for _, warning := range r.Warnings {
        // %q 已用于路径，避免名称中的换行直接伪装成新日志行。
        fmt.Fprintln(os.Stderr, warning)
    }
    fmt.Printf("已观察普通文件=%d 主动排除目录=%d 权限遗漏=%d\n",
        r.Files, r.Excluded, len(r.Warnings))
    if err != nil {
        fmt.Fprintln(os.Stderr, "扫描失败，以上仅为部分统计:", err)
        return 1
    }
    if len(r.Warnings) > 0 {
        fmt.Fprintln(os.Stderr, "扫描不完整，存在权限遗漏")
        return 3
    }
    fmt.Println("按当前排除政策扫描完成")
    return 0
}

func main() {
    os.Exit(run(os.Args[1:]))
}

在自己管理的小型目录上使用时，将根目录作为唯一参数传入。根目录为空被应用主动拒绝，不会先清理成当前目录；根是普通文件或符号链接条目时，本例也不将其当目录扫描。

# 指定自己管理的目录，程序仅遍历条目。
go run main.go ./workspace

示例程序未在本文执行，结果取决于操作者目录内容和实际权限。若脚本需要精确区分退出码，应编译后调用程序；go run 自身会报告被运行程序的非零退出状态。

0 表示按当前排除政策完成，1 表示致命错误，2 表示参数问题，3 表示没有致命错误但存在权限遗漏。已有统计行可以保留用于排查，但失败或部分结果不应覆盖一份被标记为完整的正式清单。

保留错误原因和权限边界

分类错误使用 errors.Is，而不是搜索错误消息中的 permission 字样。根因通过 %w 包装后保留，调用方仍可以判断底层错误。不要为让程序“通过”而自动提权或放宽目录权限；由操作者决定扫描账号本来应具备的范围。

日志中使用带引号转义的路径格式，便于区分文件名本身的特殊字符与日志结构。示例将权限警告保存到切片，适合小型工具；目录规模很大时，可以改成结构化事件输出并限制保留数量，同时保留准确的遗漏计数。

filepath.WalkDir 的路径采用本地操作系统分隔符，并且不跟随遍历中的符号链接。它负责遍历，不证明文件内容可读，也不把目录变成访问沙箱。后续若还要读取正文，应独立处理打开与读取错误。

用分支表准备接入

目录在读取子项前会先触发正常回调；如果读目录失败，同一路径还可能再次以错误回调出现。因此不要按“每次回调”累加目录成功数，也不要把正常目录回调当作已完成其全部子项的证据。

SkipDir 应用于目录，跳过该目录；如果在文件回调里返回它，影响的是父目录剩余条目，不是单独忽略当前文件。仅忽略一个文件应返回 nil。要主动结束整个遍历可使用 SkipAll，但它本身不以错误返回；如果“提前结束”对业务意味着不完整，必须另存一个业务标记。本文程序不使用 SkipAll，避免把提前结束混入完成状态。

这些输入分支是可供调用者选择的接入检查点，不是本文已运行的测试报告。权限现象还会受平台、账号和 ACL 影响，不能假定修改一种权限位就必然在所有环境产生同样结果。

常见问题

空目录为什么没有 nil 条目？目录本身仍是可访问条目；没有子项不表示目录对象不存在。

回调返回 nil，是不是就证明扫描成功？那只是该次回调允许继续。全局还要看后续错误、遗漏记录和外层返回值。

WalkDir 返回 nil，为什么本例还返回退出码 3？权限错误已被业务容忍，遍历器可以正常结束，但警告记录仍说明有区域未完整扫描。

需要遍历函数自己恢复 panic 吗？不应把解引用 nil 的代码缺陷当成日常访问失败。先按回调契约处理错误和条目，让访问错误正常传播。

官方文档：https://pkg.go.dev/path/filepath#WalkDir（遍历入口与路径形式）；https://pkg.go.dev/io/fs#WalkDirFunc（回调错误和跳过语义）。