Go filepath.WalkDir 怎么按扩展名过滤文件并保留错误

递归扫描目录时，最容易写错的不是 filepath.WalkDir 本身，而是把“文件过滤”和“遍历错误”混成一个判断。稳妥的写法是：先确认当前条目不是目录，再用 filepath.Ext(d.Name()) 比较扩展名；一旦回调收到 err，先把路径和错误保存下来，再决定是否继续。这样即使一个子目录不可读，其他目录里的目标文件仍能返回。

核心结论：WalkDir 默认不跟随符号链接。过滤函数只处理文件条目，错误单独收集；除根路径无法访问这种情况外，子目录读取错误可以保留后继续扫描兄弟目录。

按目录和文件分开判断，扩展名只看文件名

WalkDir 会把根目录、子目录和文件都交给同一个回调。回调参数里的 d 是 fs.DirEntry，d.Name() 只有最后一级名称，不是完整路径。因此过滤顺序应该固定为“错误优先、目录分流、符号链接策略、扩展名比较”。

下面的函数只收集 Go 源文件，并把大小写统一后比较。示例没有把目录读取错误直接返回给 WalkDir，因为那会让整棵树停止；错误会进入单独的 walkErrors 切片。

package main

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

func collectGoFiles(root string) ([]string, []error, error) {
	var files []string
	var walkErrors []error

	walkErr := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			// 先保存路径，调用方才能知道究竟是哪一级访问失败。
			walkErrors = append(walkErrors, fmt.Errorf("%s: %w", path, err))
			return nil // 子目录失败时继续访问其他兄弟项。
		}
		if d == nil || d.IsDir() {
			return nil // 目录不参与扩展名判断。
		}
		if d.Type()&os.ModeSymlink != 0 {
			return nil // 不把符号链接当作普通文件收集。
		}
		if strings.EqualFold(filepath.Ext(d.Name()), ".go") {
			files = append(files, path)
		}
		return nil
	})
	if walkErr != nil {
		return files, walkErrors, walkErr
	}
	return files, walkErrors, nil
}

func explain(err error) string {
	// errors.Is 可以识别被 %w 包装过的权限错误。
	if errors.Is(err, fs.ErrPermission) {
		return "权限不足，保留记录并安排修复"
	}
	return err.Error()
}

这里的 filepath.Ext 只取最后一个文件名元素最后一个点开始的后缀，所以 main.test.go 的扩展名仍是 .go。如果需求是严格区分大小写，把 strings.EqualFold 换成直接比较即可。

回调里的 err 要先记录，再决定是否继续

回调中的 err 不是“当前文件内容读取失败”这一种情况。根路径的初始 Stat 失败时，d 可能是 nil；目录的 ReadDir 失败时，回调会带着对应目录条目再次报告错误。此时直接写 if err != nil { return err } 很安全，但会在第一个坏目录处停止整棵树。

如果业务允许部分结果，记录后返回 nil 更合适。外层要检查 walkErrors，不能只看 walkErr == nil：后者只能说明遍历函数没有被回调主动终止，不代表每个目录都成功读取。

不要把所有错误都替换成一句“扫描失败”。用 fmt.Errorf("%s: %w", path, err) 保留路径和错误链，之后仍可通过 errors.Is 判断 fs.ErrPermission 等原因。

符号链接不跟随，是否纳入结果要明确

filepath.WalkDir 的默认行为是不跟随符号链接。一个指向目录的链接不会让遍历进入目标目录；一个指向 .go 文件的链接，仍可能作为当前目录中的非目录条目被回调，因此“是否收集链接”需要由应用规则决定。

上面的示例通过 d.Type()&os.ModeSymlink 排除链接，得到的是更保守的普通文件集合。如果确实需要处理链接目标，应把 filepath.EvalSymlinks 放在明确的后续策略里，并记录解析失败，不能误以为 WalkDir 已替你完成了目标检查。d.Info() 对符号链接描述的是链接本身，而不是目标。

把文件结果和遍历错误一起交给调用方

一个实用的扫描接口最好同时返回三类信息：已找到的文件、可继续的访问错误，以及让遍历提前终止的返回值。调用方可以在开发环境把错误打印出来，在批处理场景把部分成功和错误清单一并写入任务结果。

files, walkErrors, err := collectGoFiles("./workspace")
if err != nil {
	// 不可恢复的遍历错误不能伪装成完整成功。
	fmt.Println("遍历中止:", err)
}
for _, item := range walkErrors {
	// 部分目录失败仍保留到审计或重试清单。
	fmt.Println("访问异常:", explain(item))
}
fmt.Println("找到文件数:", len(files))

若需要跳过一个已知目录，可以在确认 d.IsDir() 后返回 fs.SkipDir；不要对普通文件返回它，因为那表示跳过该文件的父目录。要完全停止剩余遍历，才使用 fs.SkipAll 或返回一个普通非空错误。

常见问题：WalkDir 过滤与错误保留

为什么不用 filepath.Glob 递归找所有 Go 文件？

Glob 适合模式匹配，但会忽略读取目录时的 I/O 错误。需要知道哪些目录不可读时，应使用 WalkDir 并自己保存回调错误。

返回 nil 会不会让根目录错误消失？

如果回调收到根路径错误后返回 nil，错误不会作为 WalkDir 的返回值出现，但仍可保存在自己的错误切片里。只要根目录失败就必须失败，就在回调处返回该错误。

扩展名比较要不要转小写？

跨平台扫描通常用 strings.EqualFold 更宽松；若业务要求 Unix 风格的严格命名规则，则直接比较 filepath.Ext(d.Name()) == ".go"。

相关事实可在 Go 官方 filepath.WalkDir 文档 与 fs.WalkDirFunc 文档中对照参数、符号链接和错误控制语义。