Go filepath.WalkDir SkipDir 和返回错误的区别是什么

用 filepath.WalkDir 遍历目录时，fs.SkipDir 不是“返回一个可忽略的错误”，而是给遍历器的控制信号；普通非 nil error 才表示本次遍历失败。最容易写错的是：在文件回调里直接返回 fs.SkipDir，实际跳过的是这个文件所在的父目录。

三个返回值分别控制什么

filepath.WalkDir 的回调类型是 func(path string, d fs.DirEntry, err error) error。回调返回值可以按下面的决策表理解：

因此，“排除一个目录”应在目录节点判断；“发现一个坏文件就终止”才适合返回业务错误。若只是想忽略某个文件，返回 nil 即可，不要用 fs.SkipDir。

目录过滤为什么要在 d.IsDir() 分支里返回 SkipDir

例如缓存目录不需要扫描，正确写法是先判断目录名，再返回 fs.SkipDir。这样遍历器不会读取该目录的子项，但会继续处理根目录下的其他兄弟节点。

package main

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

func main() {
	err := filepath.WalkDir("./project", func(path string, d fs.DirEntry, walkErr error) error {
		// 回调错误优先处理；此时 d 可能为 nil，不能先调用 d.IsDir。
		if walkErr != nil {
			return walkErr
		}
		// 只跳过目录本身，避免误把它的父目录一起跳过。
		if d.IsDir() && d.Name() == "vendor" {
			return fs.SkipDir
		}
		// 文件只是不符合条件时，返回 nil 让同级条目继续遍历。
		if !d.IsDir() && filepath.Ext(path) == ".go" {
			fmt.Println(path)
		}
		return nil
	})
	if err != nil {
		// 统一在边界处报告遍历失败，保留原始错误链。
		fmt.Println("walk failed:", err)
	}
}

这里先处理 walkErr 是必要的。根目录状态读取失败时，回调可能拿到 d == nil；如果直接调用 d.IsDir()，就会把可诊断的文件系统错误变成 panic。

回调里的 err 和返回的 error 不是一回事

回调参数 err 表示当前路径在访问时已经遇到问题，例如根目录 Stat 失败，或目录 ReadDir 失败。它不是上一次回调的返回值。你可以按错误类型决定是记录后继续，还是终止：

err := filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
	// 目录读失败时，WalkDir 不会继续进入该目录；这里保留同级扫描机会。
	if walkErr != nil {
		if errors.Is(walkErr, fs.ErrPermission) {
			fmt.Println("skip unreadable path:", path)
			return nil
		}
		// 未知错误交给调用方，避免静默漏扫。
		return walkErr
	}
	return nil
})

这个策略的边界很清楚：权限错误被记录并放弃当前不可读分支，其他错误让全局任务失败。如果备份、合规扫描或清单生成要求“不能漏任何目录”，权限错误也应该返回，而不是一律吞掉。

常见误区和复查清单

• 想跳过一个文件却返回 fs.SkipDir：改成记录后返回 nil。
• 收到非 nil err 仍访问 d.Name()：先判断错误，避免 d 为空。
• 把所有错误都返回 nil：这会让调用方误以为扫描完整成功。
• 需要停止全部剩余路径时：可以返回 fs.SkipAll；它和只跳过当前目录不是同一语义。

相关问题

filepath.WalkDir 会跟随目录里的符号链接吗？

不会。目录中发现的符号链接默认不会被继续跟随；根路径本身是符号链接时，遍历的是它指向的目标。

SkipDir 会被 WalkDir 当成最终错误返回吗？

不会。它是遍历回调识别的特殊控制值，表示跳过范围；只有普通非 nil 错误才会让整次 WalkDir 返回失败。

什么时候应该返回自定义错误？

当漏掉任意路径都会使任务结果不可信，例如备份清单或安全扫描时，应保留原错误并让上层失败，而不是为了“跑完”而静默忽略。