fs.WalkDir 跳过隐藏目录并统计文件大小的方法

用 Go 扫描目录时，如果只想统计可见目录中的普通文件，关键不是在遍历后再过滤路径，而是在回调刚收到目录项时判断名称：对以点开头的子目录返回 fs.SkipDir，对普通文件调用 DirEntry.Info() 读取 FileInfo.Size()。这样隐藏目录的整个子树不会继续读取，文件大小也不会把目录本身混进来。

本文只聚焦 fs.WalkDir 的回调边界、错误处理和字节数统计。示例使用 os.DirFS，但统计函数接收的是 fs.FS，因此也可以换成内存文件系统做上层测试。

最小处理：在回调入口先跳过隐藏目录

fs.WalkDir 会为根目录以及树中的每个文件或目录调用回调。目录项的 Name() 只返回当前路径的最后一段，因此判断隐藏目录时，直接检查这一段是否以点开头即可。根路径通常是 .，需要单独排除，否则从当前目录开始遍历时会把根目录误当成隐藏目录。

func isHiddenDir(d fs.DirEntry) bool {
	// 根目录的 Name 可能是“.”，不能把它当成隐藏目录。
	return d.IsDir() && d.Name() != "." && strings.HasPrefix(d.Name(), ".")
}

// 回调返回 SkipDir 后，WalkDir 不会继续读取这个目录的子项。
if isHiddenDir(d) {
	return fs.SkipDir
}

这里的 fs.SkipDir 只适合目录。对文件返回它时，语义是跳过当前文件所在的父目录，容易误伤同级文件；如果只想忽略某个隐藏文件，应返回 nil，并在文件分支中直接结束当前回调。

文件大小从 DirEntry.Info 读取

DirEntry 负责描述目录读取到的条目，而字节数属于 FileInfo 的元信息。稳妥的顺序是先排除目录，再调用 d.Info()，最后只累计 Mode().IsRegular() 为真的文件。这样目录、符号链接或设备文件不会被当成普通文件统计。

func sumRegularFiles(fsys fs.FS, root string) (int64, error) {
	var totalBytes int64

	err := fs.WalkDir(fsys, root, func(path string, d fs.DirEntry, walkErr error) error {
		// WalkDir 传入的错误表示当前路径无法正常访问，不能忽略。
		if walkErr != nil {
			return fmt.Errorf("访问 %s: %w", path, walkErr)
		}
		if isHiddenDir(d) {
			return fs.SkipDir
		}
		if d.IsDir() {
			return nil
		}

		info, err := d.Info()
		if err != nil {
			// 条目可能在目录读取后被删除，保留原始错误便于定位。
			return fmt.Errorf("读取 %s 元信息: %w", path, err)
		}
		if info.Mode().IsRegular() {
			totalBytes += info.Size()
		}
		return nil
	})
	if err != nil {
		return 0, err
	}
	return totalBytes, nil
}

调用方可以把磁盘目录映射成一个文件系统：

root := "/srv/assets"
// DirFS 让 WalkDir 接收相对路径，统计逻辑不必拼接系统路径。
bytes, err := sumRegularFiles(os.DirFS(root), ".")
if err != nil {
		return fmt.Errorf("统计资源目录失败: %w", err)
}
fmt.Printf("可见普通文件总大小：%d 字节\n", bytes)

错误、符号链接和路径边界

回调中的 err 和 d.Info() 的错误不是一回事。前者通常表示根目录的初始 Stat 或某个目录的 ReadDir 失败，此时可能没有可用的 d；后者表示目录项存在，但读取它的元信息失败。示例统一向上包装错误，让调用方决定是终止任务还是记录后继续。

WalkDir 默认不跟随目录中的符号链接；而 DirEntry.Info() 对符号链接描述的是链接本身，不是目标文件。若业务只统计真实普通文件，保留 Mode().IsRegular() 判断即可。不要为了“算得更多”而自行对链接目标做递归，否则可能越出原定目录边界，也会引入重复统计。

还要注意两个容易混淆的定义：

把统计结果收口到可复用函数

把输入设计成 fs.FS 比把路径写死在函数内部更容易复用：生产环境可以传入 os.DirFS，测试或其他调用方可以传入实现了 fs.FS 的文件系统。函数只返回总字节数和错误，不打印日志，也不把“隐藏”的定义偷偷扩展成权限判断。

发布前可以按下面的清单检查实现边界：

• 根目录 . 不会被误判为隐藏目录。
• 隐藏目录返回 fs.SkipDir，普通隐藏文件是否跳过则由需求单独决定。
• 只有普通文件才累加 FileInfo.Size()，目录和链接不会直接计入。
• 回调收到的访问错误与 Info() 错误都会保留上下文并向上返回。
• 遍历根路径使用 os.DirFS 时，回调里的路径是相对于文件系统根的路径。

常见问题

为什么不能用 filepath.Walk 的 FileInfo 直接套到 fs.WalkDir？

两者回调参数不同：fs.WalkDir 先给出 DirEntry，它可以在目录读取阶段决定是否返回 fs.SkipDir；需要大小等元信息时再调用 Info()。

隐藏目录里有需要保留的文件怎么办？

不要返回 fs.SkipDir，可以把隐藏目录列入白名单，或者只对特定目录名跳过。关键是先把“隐藏”的业务定义写清楚，再决定剪枝范围。

统计结果为什么可能和磁盘工具不同？

本文统计的是普通文件的逻辑字节数，并且跳过隐藏目录、不跟随目录中的符号链接。磁盘占用还可能受块大小、稀疏文件、硬链接和工具自身过滤规则影响，不能直接当成物理占用量。