Go filepath 怎样用 WalkDir 处理根目录错误

我第一次把目录扫描接到定时任务时，真正让我困惑的不是 filepath.WalkDir 的遍历本身，而是根目录写错、被删除或没有权限时，回调里的 d 为什么突然是 nil。处理这个场景的关键是：先判断 err，再使用 d；如果根目录的初次 Stat 失败，回调会收到根路径、nil 的 DirEntry 和原始错误。

官方地址：https://pkg.go.dev/path/filepath#WalkDir

WalkDir 不会把根目录错误自动变成另一种回调。根目录无法完成初次状态检查时，应该把 d == nil 当作一个明确分支；除非业务明确允许忽略，否则把 err 返回给上层。

根目录错误为什么会进入回调

filepath.WalkDir(root, fn) 会从 root 开始遍历，并且把根本身也视为遍历对象。官方 fs.WalkDirFunc 文档把错误分成两个常见位置：初次检查根目录失败，以及进入某个目录后读取目录内容失败。

本文标题关注第一种。此时函数还没有拿到可用的目录项，所以 d 没有值；但 path 仍然是传给 WalkDir 的根路径。这个契约很适合在回调中区分“根目录没法开始”和“已经走到树中的某个目录”。

package main

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

func visit(root string) error {
	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		// 必须先处理 err；根目录初次 Stat 失败时 d 就是 nil。
		if err != nil {
			if d == nil {
				return fmt.Errorf("根目录不可访问 %q：%w", path, err)
			}
			return fmt.Errorf("访问目录项 %q 失败：%w", path, err)
		}

		// 只有 err 为空时，才可以安全读取 DirEntry 的属性。
		if d.IsDir() {
			return nil
		}
		fmt.Println(path)
		return nil
	})
}

func main() {
	if err := visit("./data"); err != nil {
		// 把遍历失败交给调用方，避免任务被误报为成功。
		fmt.Println(err)
	}
}

这段代码没有把 d == nil 当成“可以忽略”的信号，而是把它转换成带路径上下文的错误。对定时任务、索引构建或文件归档来说，这种默认更稳妥：目录不存在和权限不足都会被上层看见。

先判断 err，再决定是否访问 d

一个常见的错误写法是先写 if d.IsDir()，再在后面处理 err。根目录初次检查失败时，这会直接触发空指针问题，真正的文件系统错误反而没有被记录。

我现在会把回调固定成“错误分支在前，正常分支在后”的形状。这里的判断顺序不是为了追求某个性能数字，而是为了让两个输入状态互不混淆：错误回调不保证有 DirEntry，正常回调才可以读取名称、类型和目录属性。

不存在、权限不足和子目录错误怎么分

并不是所有根目录错误都应该让任务失败。比如一次“增量扫描”允许目录尚未创建，可以只忽略 fs.ErrNotExist；而权限不足、路径格式错误或存储设备异常，通常仍应返回。用 errors.Is 判断包装后的错误，比直接比较错误字符串可靠。

package main

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

func scanOptionalRoot(root string) error {
	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			// 只有根目录不存在时静默跳过，其他错误继续上抛。
			if d == nil && errors.Is(err, fs.ErrNotExist) {
				return nil
			}
			return fmt.Errorf("扫描 %q 失败：%w", path, err)
		}
		// 这里的 d 已经可用，正常处理文件即可。
		return nil
	})
}

要注意，回调返回 nil 就表示这次错误已经由你的代码处理。于是上面的“可选根目录”函数可能返回 nil，即使根目录从未被访问成功；如果调用方需要知道“本轮没有扫描任何目录”，就应该额外记录状态，或者选择返回一个业务错误，而不是把所有情况都抹平。

把 WalkDir 的最终错误交给上层

写完回调后还要看外层函数的返回值。WalkDir 的返回值来自遍历过程或回调返回值；如果回调把根目录错误包装后返回，外层就能统一记录、重试或让任务失败。相反，若在回调里打印一行日志后返回 nil，外层看到的就是成功。

func scan(root string) (int, error) {
	count := 0
	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			// 不在这里吞掉错误，让 scan 的调用方决定重试还是终止。
			return fmt.Errorf("WalkDir 访问 %q：%w", path, err)
		}
		if !d.IsDir() {
			count++
		}
		return nil
	})
	return count, err
}

我会把“是否允许根目录不存在”作为函数名或配置的一部分表达出来，例如 scanOptionalRoot 与 scan 分开，而不是在通用回调里无条件忽略错误。这样读代码的人能立刻知道：这是有意的容错，还是一次被隐藏的失败。

常见问题

根目录错误时 d 一定是 nil 吗？

针对根目录初次 Stat 失败这一种情况，是的，官方契约明确说明回调会收到 d=nil。目录读取失败属于另一种情况，回调通常能拿到描述该目录的 DirEntry。

回调返回 nil 后 WalkDir 会继续吗？

如果这是根目录初次检查错误，返回 nil 会让本次遍历返回成功；如果是树中某个目录读取错误，也表示该错误被处理，遍历不会把它继续上抛。是否这样做必须由业务容错策略决定。

为什么不能直接比较 err.Error()？

文件系统错误常会被包装。使用 errors.Is(err, fs.ErrNotExist) 可以按错误语义判断“路径不存在”，不依赖具体平台的错误文本。

总结一下：filepath.WalkDir 处理根目录错误时，先看 err，再看 d；d == nil 是根目录初次检查失败的重要信号。默认保留错误，需要容错时只按明确的错误类型忽略，并让外层函数清楚地区分“没有扫描”和“扫描成功”。