Go path/filepath.WalkDir 怎样跳过指定目录

在 filepath.WalkDir 的回调里，先处理传入的错误，再用 d.IsDir() 判断目录；命中排除规则时直接返回 filepath.SkipDir，即可不再进入该目录的子树。普通文件不符合筛选条件时返回 nil，不要返回 SkipDir。

例如为项目生成 Go 文件清单，可以排除任意层级的 .git、node_modules；如果只想排除项目中的 build/cache，则应按根相对路径匹配。这两种配置表达的范围不同，混用会漏掉本来需要的目录。

官方地址：https://pkg.go.dev/path/filepath

先明确排除的是目录名还是根相对路径

先把扫描目标写清楚：扫描哪个根目录、排除哪些子树、保留什么文件、遇到读取失败是否允许输出不完整清单。这里采用只读清单任务，任何访问错误都终止任务，不把权限不足解释成目录不存在。

设根目录为 workspace，内部有 build/cache 和 docs/cache。按目录名排除 cache 会同时排除二者；按相对路径排除 build/cache 则保留 docs/cache。名称规则适合明确允许全局排除的依赖目录，位置规则适合业务产物目录。

不要使用 strings.Contains(path, "cache") 判断目录。它也可能命中 cache_notes 或文件名中的相同文字。配置中的字符串按本文示例作精确匹配，不自动提供通配符、大小写折叠或忽略文件语法。

用目录判断和 SkipDir 剪掉整棵子树

下面是独立的清单程序。将 ./workspace 改成允许扫描的目录后再使用；示例没有在本文环境中执行，不把文中的行为解释作为运行记录。根目录先经过 filepath.Clean，并在回调里保留根目录本身，避免根恰好叫 node_modules 时整个任务被排除。

package main

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

func main() {
    root := filepath.Clean("./workspace")
    excluded := map[string]struct{}{".git": {}, "node_modules": {}}

    err := filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
        // 错误时条目可能为空，必须先处理错误再访问 d。
        if walkErr != nil {
            return fmt.Errorf("访问 %q: %w", path, walkErr)
        }
        if d.IsDir() {
            // 保留根目录，只按名称排除它下面的同名目录。
            if path != root {
                if _, skip := excluded[d.Name()]; skip {
                    return filepath.SkipDir
                }
            }
            return nil
        }
        // 普通文件过滤只返回 nil，不能返回 SkipDir。
        if filepath.Ext(d.Name()) != ".go" {
            return nil
        }
        rel, err := filepath.Rel(root, path)
        if err != nil {
            return err
        }
        // 输出失败也要终止；这里仅列出路径，不读取或修改文件。
        _, err = fmt.Fprintln(os.Stdout, rel)
        return err
    })
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

这里的目录名集合在回调外创建，回调只读取它。命中的目录在尝试读取其内容前就可被排除，因此它的子目录和文件不再交给这个回调处理。注意，这只能省去被剪除子树的后续工作；父目录为了枚举子项仍然需要读取。

只是不想收集某个普通文件时，回调返回 nil 即可。文件分支返回 SkipDir 的含义涉及其父目录剩余内容，不是“忽略这个文件”。因此判断 d.IsDir() 是行为正确性的核心，而非可省略的格式写法。WalkDirFunc 官方说明列出了这些返回值的控制语义。

SkipDir 应直接返回。用 fmt.Errorf 包装它会改变特殊控制值的身份，不能指望遍历器自动按包装后的值剪枝。真正的访问错误可以用 %w 包装并向调用方报告，这与控制值的用途不同。

只排除一个位置时按根相对路径匹配

按位置匹配时，先用 filepath.Rel(root, path) 得到根相对路径，再统一为配置使用的斜杠形式。这样配置不用写机器相关的绝对目录，也不把根路径的一部分误认为规则。

// directoryExcluded 只用于目录；root 必须与 WalkDir 的根参数一致。
func directoryExcluded(root, current string, blocked map[string]struct{}) (bool, error) {
    rel, err := filepath.Rel(root, current)
    if err != nil {
        return false, err
    }
    if rel == "." {
        return false, nil // 不让排除配置取消根目录扫描。
    }
    // 配置使用斜杠，实际遍历路径使用系统分隔符。
    key := filepath.ToSlash(rel)
    _, found := blocked[key]
    return found, nil
}

把这个辅助函数放入前例同一个文件，并将原来的目录名判断分支换成下面的逻辑。以下是集成片段，不是第二个完整程序；blocked 在调用 WalkDir 之前创建，目录分支放在回调内部。

// 以下片段替换前例的目录分支，blocked 在 WalkDir 外准备。
blocked := map[string]struct{}{"build/cache": {}, "third_party/vendor": {}}

// 回调中仍须首先处理 walkErr，再使用 d。
if d.IsDir() {
    skip, err := directoryExcluded(root, path, blocked)
    if err != nil {
        return err
    }
    if skip {
        return filepath.SkipDir // 原样返回控制值，不用 fmt.Errorf 包装。
    }
    return nil
}

规则 build/cache 的目录命中后，整棵子树被排除，所以不必再为 build/cache/tmp 写重复配置。名称为 build/cache-old 的目录不会命中精确规则；不要改成直接字符串前缀比较，否则会再次扩大排除范围。

实际配置应采用同一种规范：根相对、斜杠分隔、没有起止斜杠，不使用 . 或 .. 路径元素。本文把规则固定在代码里；若改成配置文件，应在扫描前拒绝不符合规范的值，并把错误交给配置维护者，不要静默清洗成另一个有效规则。Windows 的卷名和绝对路径也不属于这套根相对配置。

字符比较与操作系统的路径查找语义并不相同。这里的 map 查找区分大小写，即使某些文件系统查找名称时不区分大小写，也不能据此认定配置 Cache 会命中回调给出的 cache。需要支持这类行为时，应先明确团队的命名和比较约定。

把读取失败和主动排除分别记录

目录不可读取和目录被规则排除，是两种完全不同的结果。前例对 walkErr 一律报错退出，适合要求完整结果的清单任务。若业务允许尽力扫描，可以在回调错误分支记录失败后返回 nil，但最终结果必须标明不完整，不能沿用“全部成功”的状态。

传入错误时，不要先调用 d.Name() 或 d.IsDir()。根目录访问失败时，条目可能为空。目录读取失败还可能使同一路径再次进入回调：一次是读目录前，一次是报告读取错误。计数器应区分访问事件和唯一目录，不能将回调调用次数直接当作扫描目录数。

日志可以记录任务标识、规则标识、根相对路径、原因类型和最终完整性状态。主动剪枝记录为策略排除；失败记录为访问错误。文件名本身可能含有换行或敏感业务信息，应采用结构化字段或带转义的输出方式，并按实际日志权限处理完整路径。

若先逐行输出、后遇到错误，输出文件可能已经包含部分内容。退出码非零告诉调用方这份结果不能当完整清单。需要对外提供最终文件时，可以在受控位置写临时产物，扫描成功并确认输出写入成功后再提交；失败则保留错误状态，不让下游仅凭“文件存在”判断成功。本文代码只是标准输出清单，没有实现产物提交协议。

限定扫描权限并处理符号链接边界

排除规则用于选择扫描范围，不能承担访问权限控制。运行清单任务不需要提升系统权限；给进程必要的目录读取和遍历权限即可。如果某个需要纳入的目录不可访问，应调整任务范围或按管理流程处理权限，不能为了完成清单直接以高权限重跑。

filepath.WalkDir 不跟随符号链接。前例的文件扩展名判断并不意味着所有输出项都是普通文件：一个名字以 .go 结尾的符号链接，也可能被输出为条目路径。若清单只允许普通文件，应另外判断条目类型；如需调用 d.Info() 获取信息，也必须处理该调用的错误。

尤其不能把“不跟随链接遍历”等同于“之后打开路径也不会跟随链接”。清单生成后，目录内容仍可能变化；另一个阶段按这些路径打开文件时，需要独立定义链接处理和访问约束。本文只列路径，不读取文件内容，不删除目录，也不宣称提供沙箱隔离。

遍历结果采用字典序，但遍历不是文件系统快照。扫描期间的新增、删除、重命名会影响结果。大目录还会带来目录项内存开销，不能把 WalkDir 理解为“每层永远只持有一个文件名”。剪掉大子树通常能减少工作量，具体收益取决于目录布局，不应凭示例声称固定性能提升。参见filepath.WalkDir 文档。

交付前按这些情形核对行为

读者把示例接入项目时，可以在自己有权使用的临时目录里准备以下情形，比较实际清单与业务期望。下面是建议的预期行为，不是本文执行过的测试结果。

返回 nil 会不会跳过目录内容？

不会。目录回调返回 nil 允许继续遍历；要剪除目录子树，须在目录分支返回 SkipDir。普通文件返回 nil 则只是正常继续。

能直接读取 .gitignore 作为规则吗？

本文代码不会解析它。忽略文件还涉及模式语法、否定规则和目录层级等语义，需要单独实现或选择明确支持这些规则的组件，不能把每一行直接塞进目录名集合。

根目录要排除时怎么处理？

本文有意保留根。若业务允许整棵树不扫描，应在任务入口就返回明确的“不扫描”状态，避免调用方把没有输出误认为完整空目录。

最终把三个判断分开维护：目录规则决定哪些子树不进入，文件规则决定哪些条目加入清单，错误策略决定结果能否标记完整。这样调整排除配置时，范围、失败原因和下游结果都能被清楚解释。