filepath.WalkDir 遇到权限目录的错误处理

我在把目录扫描接入自动化任务时，最容易误判的一点是：filepath.WalkDir 不会替你吞掉权限错误。某个目录无法读取时，错误会作为回调参数传进来；回调返回什么，才决定任务是继续、跳过还是整体失败。

处理权限目录时，先判断 err，再判断 d 是否可用。入口路径访问失败通常应直接返回错误；子目录读取失败则可以记录后返回 nil 继续扫其他分支，或在确认 d.IsDir() 后返回 filepath.SkipDir。不要在 d == nil 时直接调用 d.IsDir()，也不要把所有错误都当成“无权限”。

本文对应的官方资料：https://pkg.go.dev/path/filepath、https://pkg.go.dev/io/fs

WalkDir 回调里先看 err

WalkDir 的回调类型是 fs.WalkDirFunc，核心参数可以理解为三件事：当前路径 path、当前目录项 d，以及访问这个路径时遇到的 err。正常访问时 err == nil；只要读取入口、读取目录内容或获取某个条目的信息失败，回调就会收到非空错误。

我现在会把回调分成两个阶段：先处理错误分支，再处理正常的文件和目录分支。这样既能防止空指针，也能让“权限错误的降级策略”集中在一个位置。

package main

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

func walk(root string) error {
	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		// 访问失败时先处理 err，避免在 d == nil 时调用 d.IsDir。
		if err != nil {
			fmt.Printf("访问失败 path=%q err=%v\n", path, err)
			// 返回 nil 表示放弃当前路径，继续处理可访问的其他分支。
			return nil
		}

		// err 为空后，d 才可以安全地用于判断文件或目录。
		if d.IsDir() {
			fmt.Printf("目录: %s\n", path)
			return nil
		}
		fmt.Printf("文件: %s\n", path)
		return nil
	})
}

这段代码的重点不是打印目录，而是错误分支的位置。权限目录读取失败时，遍历器已经知道当前路径无法继续向下读取；回调返回 nil 后，程序可以继续接收其他兄弟路径的回调。它适合“尽可能收集结果”的任务，但不适合要求目录完整性的备份或审计任务。

入口失败和子目录失败不是一回事

权限错误常见于两种位置。第一种是入口本身不可访问，类似对根路径执行初始 Lstat 失败，此时回调里的 d 可能是 nil。第二种是已经进入某个目录，但读取它的内容失败；这种情况下回调通常仍能拿到表示该目录的 DirEntry，只是 err 非空。

两者都叫“权限错误”，但业务含义不同：入口失败意味着任务没有扫描起点，继续执行很可能产出一个看起来成功、实际为空的结果；子目录失败只影响一棵子树，其他目录仍可能有价值。

func walkWithRootPolicy(root string) error {
	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			// 根路径失败时不能把空结果当作成功，保留原始错误给调用方。
			if path == root {
				return fmt.Errorf("打开扫描根目录 %q: %w", path, err)
			}

			// 子路径失败只影响当前分支，记录后继续处理其他分支。
			fmt.Printf("跳过不可读路径 %q: %v\n", path, err)
			return nil
		}

		// 只有 err 为空时才访问 d；这里可以安全地区分目录和文件。
		if d.IsDir() {
			fmt.Printf("检查目录 %q\n", path)
		}
		return nil
	})
}

这里用 path == root 识别入口，是为了保持示例简单。如果调用方会把路径清洗、绝对化或拼接成不同形式，最好先得到一个规范化的根路径，再把同一个变量传给 WalkDir 和回调策略。错误包装使用 %w，调用层仍可用 errors.Is 判断原因。

什么时候用 SkipDir

filepath.SkipDir 是控制遍历范围的特殊返回值，不等同于“所有错误都跳过”。在一个已经确认是目录的回调里返回它，表示不再进入当前目录；如果回调发生在某个文件上，特殊值的语义还会涉及它的父目录。因此遇到 err != nil 时，不能只写一行无条件的 return filepath.SkipDir。

func walkAndSkipUnreadableDirs(root string) error {
	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			// d 非空且表明当前项是目录时，SkipDir 的语义最明确。
			if d != nil && d.IsDir() {
				fmt.Printf("目录不可读，跳过子树 %q: %v\n", path, err)
				return filepath.SkipDir
			}

			// 文件或入口的 d 可能为空；返回原错误，避免误跳过父目录。
			return fmt.Errorf("遍历 %q: %w", path, err)
		}

		// 正常目录可以继续深入，文件则交给后续业务处理。
		return nil
	})
}

如果目标只是“跳过不可读子树”，这个策略比无条件返回 nil 更容易留下明确的审计日志；如果目标是“尽量得到所有可读文件”，返回 nil 也合理，因为目录读取已经失败，遍历器不会凭空得到该目录的子项。

用 errors.Is 区分权限错误和其他错误

不要通过错误字符串是否包含 permission 来判断原因。Go 的错误可能被多层包装，操作系统之间的文本也不同。可以用 errors.Is(err, fs.ErrPermission) 判断权限类错误；其他错误则保持原样返回，避免把磁盘故障、断开的挂载点或路径损坏伪装成可忽略问题。

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

func walkByErrorKind(root string) error {
	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err == nil {
			return nil
		}

		// 权限问题可以按业务降级，其他错误保留给上层决定。
		if errors.Is(err, fs.ErrPermission) && path != root {
			fmt.Printf("权限不足，忽略子路径 %q: %v\n", path, err)
			return nil
		}
		return fmt.Errorf("WalkDir 处理 %q: %w", path, err)
	})
}

“权限错误”也不意味着一定能降级。比如安全审计、配置发布、备份清单等任务，缺少一棵目录就可能使结果不可信；这类任务应该把错误继续返回，并在上层标记任务失败。日志里至少保留路径和原始错误，必要时再记录任务 ID 或扫描范围，不要只输出一句“跳过失败目录”。

把策略做成可读的任务配置

我更倾向于把错误处理策略放在一个小函数中，而不是散落在多个回调分支里。常见的三种策略可以这样理解：

这里有一个容易忽略的边界：返回 nil 只表示回调不再把这次错误向上抛出，不表示目录突然可读，也不表示该目录的内容会被补扫。调用方应在最终结果里保留“部分完成”或“跳过路径”的信息，否则用户很难判断空缺来自没有文件，还是来自没有权限。

测试时覆盖四个边界

权限位测试在不同操作系统、用户身份和文件系统上可能表现不同，所以测试重点应放在回调策略，而不是假设所有环境都稳定返回同一条错误文本。可以把回调策略抽成可测试函数，再用构造好的 path、d 和 err 组合覆盖边界。

1. 入口错误：d == nil、err != nil，确认不会发生空指针，并且错误能到达调用方。
2. 子目录读取错误：d != nil 且 d.IsDir() 为真，确认选择 nil 或 SkipDir 的策略符合任务目标。
3. 文件访问错误：不要把文件错误误判成目录错误，检查是否应该终止或只记录。
4. 非权限错误：确认不会因为字符串相似而被静默忽略，原始错误仍可被 errors.Is 追踪。

如果测试需要创建真实权限目录，运行用户、容器权限和 Windows ACL 都会影响结果；这类测试可以单独标记为环境相关。核心单元测试仍应直接验证回调的返回值和错误包装关系，避免把“本机当前能否制造权限错误”当成唯一质量依据。

常见问题

WalkDir 遇到权限目录会自动继续吗？

不会。错误会进入回调，回调返回非空错误时遍历通常会停止；只有回调返回 nil 或合适的特殊值，任务才会按策略继续。

err 不为空时 d 一定是 nil 吗？

不一定。入口或条目状态获取失败时可能没有可用的目录项；目录读取失败时可能仍有表示该目录的 DirEntry。因此应先判断 d != nil，再调用 d.IsDir()。

为什么不直接对所有错误返回 nil？

这样可以得到更多可读结果，但也会隐藏入口失败、挂载异常和磁盘错误。只有结果允许部分缺失时才适合这么做，并且应把跳过路径记录下来。

SkipDir 能跳过文件吗？

它主要用于跳过目录。对非目录回调返回特殊值时，遍历器的语义会关联到父目录，所以错误分支中最好只有在明确拿到目录项且确认是目录时才返回 SkipDir。

如何判断权限错误？

优先使用 errors.Is(err, fs.ErrPermission)，不要只匹配错误字符串。对无法稳定归类的系统错误，应保留原错误交给上层处理。

最后可以把原则压缩成一句话：WalkDir 的权限处理不是“遇错就跳过”，而是先区分入口和子树，再根据任务是否允许部分结果选择 return nil、filepath.SkipDir 或返回原错误。只要保证 d 的空值判断和原始错误链不被破坏，目录遍历就能在可用性与结果可信度之间取得清楚的取舍。