Go filepath.WalkDir 如何跳过隐藏目录：SkipDir、DirEntry 与遍历剪枝

做目录清单时，直接递归所有子目录很快就会把 .git、node_modules 和 build 里的文件也算进去。Go 的 filepath.WalkDir 允许在回调里识别目录，并用 SkipDir 立刻剪掉当前分支。关键不是“跳过一个名字”，而是只在确认当前条目是目录时返回这个特殊值。

先定义一个只收集源码文件的目录清单

这个小工具接收根目录，把名字以 .go 结尾的文件打印出来，同时跳过缓存和构建目录。DirEntry 提供目录判断，不需要为了剪枝再调用一次 os.Stat。

核心代码：DirEntry 决定是否返回 SkipDir

package main

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

var ignored = map[string]bool{
    ".git":         true,
    "node_modules": true,
    "build":        true,
}

func listGoFiles(root string) ([]string, error) {
    var files []string
    err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            return fmt.Errorf("visit %s: %w", path, walkErr)
        }
        if entry.IsDir() && ignored[entry.Name()] {
            return filepath.SkipDir
        }
        if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".go") {
            files = append(files, path)
        }
        return nil
    })
    return files, err
}

func main() {
    files, err := listGoFiles(".")
    if err != nil {
        panic(err)
    }
    for _, path := range files {
        fmt.Println(path)
    }
}

控制流只有一个关键分叉：entry.IsDir() 为真且名字命中 ignored 时返回 SkipDir；普通目录返回 nil，遍历才会继续向下。文件分支再检查 .go 后加入 files。

本地运行时要核对三种结果

先准备一个最小目录：

mkdir -p demo/pkg demo/build demo/node_modules
printf 'package pkg\n' > demo/pkg/main.go
printf 'package build\n' > demo/build/generated.go
printf 'package deps\n' > demo/node_modules/dep.go
go run . demo

示例代码中的根目录可以改成命令行参数；验收时应看到 demo/pkg/main.go，看不到 demo/build/generated.go 和 demo/node_modules/dep.go。如果把根目录直接设为某个被忽略目录，它本身仍会作为遍历起点交给回调，这正是需要单独测试的边界。

错误回调与 SkipDir 不能混用

先处理 walkErr

当路径没有访问权限或目录在遍历过程中消失时，回调可能拿不到可用的 entry。所以示例先判断 walkErr，再调用 entry.IsDir()，避免错误路径上发生空对象访问。

文件返回 SkipDir 没有剪枝意义

SkipDir 的语义是跳过当前目录的剩余内容。对普通文件返回它不会替代文件错误处理，也不能把同级其他条目一起跳过；需要跳过文件时直接返回 nil 并不加入 files。

忽略规则要按目录名还是相对路径

示例按 entry.Name() 匹配，因此任意层级的 build 都会被跳过。如果只有根目录下的某个路径需要忽略，应改用相对路径判断，避免误伤子项目中的同名目录。

把剪枝规则写进测试

测试目录至少包含一个保留的 pkg/main.go、一个被忽略的 build/generated.go，以及普通文本文件。断言结果只含保留文件，并确认返回错误为空；再单独调用被忽略目录作为根路径，验证根边界符合产品预期。

func TestListGoFilesPrunesBuild(t *testing.T) {
    // 创建 pkg/main.go 与 build/generated.go。
    // 调用 listGoFiles(root)，断言只返回 pkg/main.go。
}

相关问题

filepath.WalkDir 和 filepath.Walk 怎么选？

只需要目录类型和名称时，WalkDir 直接提供 DirEntry，剪枝代码更紧凑；需要完整文件信息时再考虑调用 Info，不要为每个条目无条件做额外系统调用。

为什么不用 strings.Contains 判断整个路径？

路径字符串可能包含同名片段，例如项目目录叫 build-tools。按 DirEntry.Name() 判断目录名边界更明确；复杂规则再转成经过清洗的相对路径。

遇到一个权限错误应该继续吗？

清单工具可以记录错误后继续，但备份或安全扫描通常应把错误返回给调用方。示例选择立即返回，保证“清单完整”不会被误解为“部分成功”。

小结

filepath.WalkDir 的剪枝点就在回调：先处理 walkErr，再用 DirEntry 判断目录，命中忽略规则时返回 SkipDir。文件分支继续收集，错误分支明确收口，这条控制流既短，也足够让测试锁住目录遍历边界。