Go fs.WalkDir 为什么不会自动遍历符号链接

用 io/fs.WalkDir 遍历目录时，目录里的符号链接只会以一个目录项出现，链接指向的目录不会被继续展开。这不是漏遍历，而是 API 的明确边界：如果 root 自身是符号链接，WalkDir 会先按目标路径开始；如果符号链接位于被遍历的目录内部，则不会自动跟随。

官方文档：https://pkg.go.dev/io/fs

因此，排查这类问题时，先把“根路径是链接”和“子项是链接”分开，再决定是记录链接、读取链接目标，还是完全禁止链接参与业务处理。

先看清 WalkDir 的基线行为

我在处理文件索引时遇到过一个很容易误判的现象：实际目录中能看到一个指向共享目录的链接，但索引结果里只有这个链接名，没有共享目录下的文件。基线其实很简单：普通子目录会递归，目录中的符号链接不会递归，遍历顺序仍按目录项的字典序组织。

这样设计有两个直接好处。第一，遍历不会因为多个链接指向同一棵树而重复展开；第二，不会因为链接环路把一次目录扫描变成无限递归。链接本身仍然会进入回调，所以应用可以把它记录为一种特殊文件类型。

为什么 root 自身是链接时又能走进去

WalkDir 开始工作时，会先处理传入的 root。官方实现对根路径使用会跟随链接的状态查询，因此当根路径本身是符号链接时，会以它指向的目标作为遍历起点。这个特例只影响起点，不会改变后续目录内部链接的规则。

可以把它理解成两种不同的意图：传入一个链接作为入口，通常表示“我要扫描这个入口最终指向的树”；扫描过程中遇到链接，则需要由调用方决定是否把它视作另一个入口。WalkDir 选择了前者自动处理、后者保持不展开。

在回调里识别目录中的符号链接

不要用 d.IsDir() 推断“它是不是可以继续递归”。对目录项来说，应该先判断类型位；发现符号链接后，可以记录、跳过，或者交给后续的显式策略。

package main

import (
	"fmt"
	"io/fs"
)

func inspectTree(fsys fs.FS) error {
	return fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			// 访问权限或坏链接等错误交给上层决定是否终止。
			return err
		}
		if d == nil {
			// 回调可能收到没有目录项的错误通知，避免继续解引用。
			return nil
		}
		if d.Type()&fs.ModeSymlink != 0 {
			// 目录中的链接只记录，不把它当成可递归目录。
			fmt.Printf("symlink: %s\\n", path)
			return nil
		}
		fmt.Println(path)
		return nil
	})
}

这里的关键不是“发现链接后返回什么”，而是先把链接项从普通文件、普通目录中分离出来。若只是做清单或索引，记录路径通常已经足够；若业务要求读取链接目标，就要进入下一步的显式处理。

需要目标内容时，为什么必须显式处理

如果产品真正想扫描链接指向的内容，建议把“发现链接”和“展开目标”拆成两个动作。前者在 WalkDir 回调里完成，后者由单独的策略函数负责，并且要记录已经访问过的目标，避免多个链接重复扫描或形成环路。

在抽象的 fs.FS 上，可以按实现能力使用 fs.ReadLink 读取链接目标；如果底层文件系统没有提供读取链接的能力，就应该把错误作为能力不支持处理，而不是假设所有 FS 都能解析链接。

import (
	"fmt"
	"io/fs"
)

func linkTarget(fsys fs.FS, path string) (string, error) {
	target, err := fs.ReadLink(fsys, path)
	if err != nil {
		// FS 未提供 ReadLink 能力，或链接本身不可读。
		return "", fmt.Errorf("read symlink %q: %w", path, err)
	}
	return target, nil
}

真正做递归展开时，还要为目标路径建立访问集合，并明确是否允许跨出当前根目录。这个边界属于业务安全策略，不能靠 WalkDir 的默认行为替你决定。

结果对比：把三种项分开就不会误诊

另一个容易忽略的基线是字典序遍历：它让结果更稳定，但实现需要先读入一个目录的目录项再继续。因此，符号链接不自动展开既是语义选择，也避免了额外的树重复和环路判断成本。

最后记住这三个边界

• 目录内的符号链接不会自动递归，链接项本身仍会进入回调。
• root 自身是符号链接时，目标会作为遍历起点；不要把这个特例推广到所有子项。
• 需要读取或展开目标时，显式检查 ModeSymlink、文件系统能力、访问集合和根目录边界。

所以，看到“WalkDir 少了链接目标里的文件”时，先不要改成另一个遍历 API。先确认链接出现在哪一层，再把“是否跟随”和“如何防止重复或越界”写成调用方自己的策略，这才是符合 io/fs 设计的处理方式。

相关问题

WalkDir 会不会把符号链接当成目录？

目录内的符号链接作为链接项回调，不会因为目标是目录就自动进入目标树。

怎样只统计真实目录而不统计链接目录？

在回调中先检查 d.Type()&fs.ModeSymlink，确认不是链接后再使用目录判断。

使用 ReadLink 就会自动递归吗？

不会。读取目标只是得到链接指向的名称，是否打开、加入队列和继续遍历仍由应用代码负责。