当前位置：首页 > 文章列表 > Golang > Go问答 > Go filepath.WalkDir 遇到 fs.SkipDir 为什么有两种含义：目录跳过与遍历终止

Go filepath.WalkDir 遇到 fs.SkipDir 为什么有两种含义：目录跳过与遍历终止

来源：17golang原创 2026-08-29 17:22:54 0浏览收藏

给目录做扫描排除时，最容易误判的一行代码就是 return fs.SkipDir。它不是“永远跳过当前目录”这么简单：回调当前拿到的是目录，才会跳过这个目录；回调当前拿到的是文件，返回同一个值会让 WalkDir 跳过该文件所在父目录的剩余项。判断点只有一个：当前的 fs.DirEntry 到底是不是目录。

需要排除目录时，在目录分支返回 fs.SkipDir；需要跳过某个文件并继续扫描同级文件时，返回 nil，不要把文件分支也写成 fs.SkipDir。

要点速览

fs.SkipDir 对目录表示跳过整个目录树。
对文件返回 fs.SkipDir，表示跳过它的父目录剩余项。
文件过滤通常返回 nil，这样兄弟文件仍会继续访问。
真正停止全部遍历应返回错误或使用 fs.SkipAll。

同一返回值，为什么会走两条路径

filepath.WalkDir 实际使用的是 io/fs 的 WalkDirFunc。回调每次收到三个值：当前路径 path、目录项 d 和可能的访问错误 err。当 err 不为空时，应先决定是记录并继续，还是把错误返回给遍历器。

当 err == nil 时，d.IsDir() 才是这道题的分叉开关。目录节点返回 fs.SkipDir，遍历器不会进入它；普通文件节点返回 fs.SkipDir，语义则退化为“不要再访问当前父目录的其他项”。这也是它和“过滤掉一个文件”之间的差别。

WalkDir 在目录节点判断 d.IsDir 后用 fs.SkipDir 跳过目录树的控制流

先写一个能看出访问顺序的例子

下面的示例扫描 ./sample，想排除名为 .git 的目录，并忽略扩展名为 .tmp 的文件。关键是：排除目录和忽略文件不能共用同一个返回值。

package main

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

func main() {
    err := filepath.WalkDir("./sample", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }

        if d.IsDir() && d.Name() == ".git" {
            return fs.SkipDir
        }
        if !d.IsDir() && strings.HasSuffix(d.Name(), ".tmp") {
            return nil
        }

        fmt.Println(path)
        return nil
    })
    if err != nil {
        panic(err)
    }
}

执行到 .git 时，回调返回 fs.SkipDir，因此不会再看到 .git/config 等后代路径。执行到 cache.tmp 时只是不打印它，随后同级的 main.go 仍会被访问。