Go fs.WalkDir 怎么跳过指定子目录

在 fs.WalkDir 的回调里，先确认当前条目是目录，再在命中目标目录时返回 fs.SkipDir，就能跳过这个目录以及它下面的所有内容。关键不是“看到不想要的文件就忽略”，而是必须在目录节点上返回这个特殊值。

官方文档：https://pkg.go.dev/io/fs

我第一次给代码扫描工具加排除目录时，只在回调中对 .git 里的文件返回 nil。结果虽然没有处理这些文件，遍历器仍然进入了整个对象目录，耗时几乎没变。后来把判断提前到目录节点并返回 fs.SkipDir，才真正剪掉了这棵子树。

最小写法：命中目录时返回 fs.SkipDir

下面的例子从当前工作目录创建一个 fs.FS，跳过任意层级中名为 .git、vendor 或 node_modules 的目录。回调先处理 err，因为根目录读取失败时 d 可能为 nil，此时不能直接调用 d.IsDir()。

package main

import (
	"fmt"
	"io/fs"
	"log"
	"os"
)

func main() {
	// 名称集合适合排除任意层级中同名的缓存或依赖目录。
	excluded := map[string]struct{}{
		".git":         {},
		"vendor":       {},
		"node_modules": {},
	}

	err := fs.WalkDir(os.DirFS("."), ".", func(path string, d fs.DirEntry, err error) error {
		// 必须先处理遍历错误；出错时 d 可能不可用。
		if err != nil {
			return err
		}

		// 只在目录节点返回 SkipDir，才能安全剪掉它的整棵子树。
		if d.IsDir() {
			if _, skip := excluded[d.Name()]; skip {
				return fs.SkipDir
			}
			return nil
		}

		// 这里放真正的文件处理逻辑。
		fmt.Println(path)
		return nil
	})
	if err != nil {
		log.Fatal(err)
	}
}

这段代码里的 path 使用 io/fs 的斜杠分隔形式。由于根是 os.DirFS(".")，回调收到的根路径是 .，子项会是 cmd/tool/main.go 这样的相对路径，不需要拼接操作系统绝对路径。

为什么返回 fs.SkipDir 就能剪掉整棵子树

WalkDir 会在读取一个目录的内容之前调用回调。这一点很实用：当回调在目录节点返回 fs.SkipDir 时，遍历器连这个目录的条目列表都不需要继续读取，更不会访问它的后代。对于依赖目录、版本库对象目录或大型缓存目录，这比进入后再逐个忽略文件更直接。

这里还有两个容易混淆的返回值：

• nil：当前条目处理完成，继续遍历。
• fs.SkipDir：跳过当前目录；如果误用于普通文件，会跳过该文件所在目录中余下的条目。
• fs.SkipAll：停止所有剩余遍历，但 WalkDir 不把它作为最终错误返回。
• 其他非空错误：立即停止，并由 WalkDir 返回该错误。

按目录名跳过，还是按相对路径跳过

按 d.Name() 匹配写起来最短，但它会排除每一个同名目录。例如你排除 cache，那么 service/cache 和 testdata/cache 都不会被访问。如果只想跳过项目根下的某个目录，应改为匹配完整的相对路径。

下面的版本只跳过 internal/generated 和 assets/cache，不会误伤其他位置的 generated 或 cache 目录。

package main

import (
	"fmt"
	"io/fs"
	"log"
	"os"
)

func main() {
	// 路径集合用于精确排除某几棵子树。
	excludedPaths := map[string]struct{}{
		"internal/generated": {},
		"assets/cache":       {},
	}

	err := fs.WalkDir(os.DirFS("."), ".", func(path string, d fs.DirEntry, err error) error {
		// 直接返回真实错误，避免把读取失败误判成排除规则。
		if err != nil {
			return err
		}

		// 路径命中和目录判断必须同时成立。
		if d.IsDir() {
			if _, skip := excludedPaths[path]; skip {
				return fs.SkipDir
			}
		}

		if !d.IsDir() {
			// 示例任务：只输出真正被访问到的文件。
			fmt.Println(path)
		}
		return nil
	})
	if err != nil {
		log.Fatal(err)
	}
}

多规则组合时，把“是否跳过”收进一个函数

规则增多以后，最难维护的往往不是 WalkDir，而是散落在回调里的条件。我的做法是把名称规则和路径规则放进同一个判断函数，并让它只接收目录条目。这样回调仍然保持“处理错误、判断目录、处理文件”三个清楚的分支。

可以采用这样的判断顺序：先用 d.IsDir() 排除普通文件，再检查精确路径集合，最后检查全局目录名集合。精确路径适合项目私有生成目录，名称集合适合 .git、node_modules 这类无论出现在哪里都不希望深入的目录。

四个边界别漏掉

不要在普通文件上返回 fs.SkipDir

官方定义里，普通文件回调返回 fs.SkipDir 会跳过该文件父目录中剩余的条目，而不只是跳过这个文件。只想忽略一个文件时直接返回 nil 即可。

根目录也会进入回调

WalkDir 会把根本身交给回调。如果排除规则可能命中根路径或根目录名，要先决定这是预期的“整次不遍历”，还是配置错误。需要停止整个遍历时，语义更明确的是返回 fs.SkipAll。

错误参数要在目录判断之前处理

根的初始状态读取失败时，回调会收到非空 err，并且 d 为 nil。目录读取失败时，同一路径可能先以无错误状态调用一次，读取失败后再以非空错误调用一次。把 err 分支放在最前面，可以避免空指针，也能明确决定是停止还是容忍某类错误。

WalkDir 默认不跟随遍历中遇到的符号链接

目录树中的符号链接不会被当成目标目录继续向下遍历，因此通常不需要再对链接目标做排除。如果传入的根本身是符号链接，则其目标会被遍历；根路径来自外部输入时，要单独考虑这一边界。

怎么确认确实没有进入目标目录

不要只看最终业务结果，最好临时记录回调收到的路径。在一个小型测试目录里放入两个同名目录，再分别用名称规则和路径规则执行：名称规则应让两棵子树都不出现，路径规则则只消失指定的那一棵。确认后再移除临时输出，接入真正的扫描、打包或统计逻辑。

相关问题

fs.WalkDir 和 filepath.WalkDir 的路径有什么区别？

io/fs.WalkDir 面向 fs.FS，路径统一使用斜杠，并以传入的根路径为前缀；filepath.WalkDir 面向操作系统文件路径。排除逻辑相同，但路径集合要按你实际调用的 API 形式保存。

跳过目录后，WalkDir 会把 fs.SkipDir 当成错误吗？

不会。fs.SkipDir 是控制遍历的特殊值，正确用于目录节点时只改变遍历范围。最终返回值仍可为 nil。

只想跳过目录里的某类文件怎么办？

对文件名或扩展名命中时返回 nil，不要返回 fs.SkipDir。后者会影响父目录中后续条目，范围比“忽略当前文件”更大。

实际项目里，我会把“目录剪枝”和“文件过滤”分开：目录剪枝只在 d.IsDir() 为真时返回 fs.SkipDir，文件过滤则始终通过 nil 继续遍历。这个界限守住以后，排除规则既快，也不容易误跳其他文件。