Go filepath.WalkDir 出错时怎么排查访问错误

我在用 Go 扫描用户上传目录时，最初把所有异常都当成“某个文件打不开”。真正排查后发现，filepath.WalkDir 的访问错误至少有三种入口：根路径连 os.Lstat 都失败、目录读取失败，以及回调处理某个子项时主动返回错误。排查的关键不是继续加日志，而是先判断 err 出现在哪一次回调，以及此时 d 是否存在。

先分清 WalkDir 的三类错误入口

WalkDir 会把根路径也交给回调。根路径不存在或没有权限时，回调形如 path=root, d=nil, err!=nil；此处如果先读取 d.IsDir()，排查代码反而会产生新的空指针问题。目录本身已经被发现、但读取子项失败时，回调会再次收到同一路径和非空错误。子文件的错误则通常带着具体子路径。

这三个入口的处理目标不同：根路径错误通常意味着本次任务无法开始；目录读取错误可以按业务决定跳过还是终止；子项错误需要结合文件类型和任务容忍度判断。不要只打印 err.Error()，把阶段写进日志更容易看出问题。

回调里先处理 err，再访问 DirEntry

下面这个处理器保留了错误阶段，并把 d == nil 当作根路径失败的信号。示例只表达排错策略，不代表已经在本机执行：

func walk(root string) error {
	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		// 根路径或当前目录读取失败时，d 可能为空，必须先处理 err。
		if err != nil {
			if d == nil {
				return fmt.Errorf("访问根路径 %q: %w", path, err)
			}
			// 目录权限问题按业务容忍时只跳过当前目录，不吞掉根路径失败。
			if d.IsDir() && errors.Is(err, fs.ErrPermission) {
				return filepath.SkipDir
			}
			return fmt.Errorf("访问 %q: %w", path, err)
		}

		// 当前条目已确认可读；这里再判断目录或文件类型。
		if d.IsDir() {
			return nil
		}
		if d.Type().IsRegular() {
			fmt.Println("发现文件:", path)
		}
		return nil
	})
}

注意，目录读取失败时标准库会把已知目录条目传回回调，因此可以按目录分支处理。若业务不能容忍漏扫，应直接返回包装后的错误，让上层知道本次结果不完整。

SkipDir 和 SkipAll 不要混用

filepath.SkipDir 适合“这个目录不再深入，但其他同级项继续”。它并不是普通错误；WalkDir 会识别这个特殊返回值。对文件回调返回 SkipDir 时，语义是跳过该文件所在的父目录，容易把更多文件一起漏掉。需要停止剩余所有项时，返回 fs.SkipAll 更直白。

我的习惯是先写一张小表再定返回值：

最后检查路径、符号链接和日志信息

filepath.WalkDir 使用目标操作系统的路径分隔符，日志里不要手工把路径拼成 URL 风格。它也不会跟随目录中的符号链接；如果业务需要处理链接目标，应单独设计策略，不要把“没有遍历进去”误认为访问错误。文件系统遍历具有外部变化，目录可能在回调期间被删除，所以对非根路径的短暂失败要保留完整路径和错误类型。

一条实用的排查日志至少包含 stage、path、is_dir 和原始错误。这样看到 permission denied 时，能立即判断是入口目录、子目录还是单个文件，而不是靠猜。

相关问题

为什么 d 会是 nil？

最常见是根路径的初始状态检查失败，此时只有路径和错误可用。先判断 err，再判断 d。

忽略目录权限错误会不会返回 nil？

如果回调对已知目录错误返回 filepath.SkipDir，遍历可以继续其他路径，但结果代表“部分完成”，业务应自行记录。

WalkDir 会遍历符号链接目标吗？

不会跟随目录中的符号链接。需要链接目标时，应在业务层明确调用相应的 stat 或打开逻辑，并处理循环风险。