Go filepath.WalkDir 符号链接为什么没有被遍历怎样构造最小复现

目录扫描程序里经常会遇到一个看起来像“漏文件”的现象：真实目录可以继续遍历，但目录中的符号链接只回调了一次，链接目标里的文件却没有出现。对 filepath.WalkDir 来说，这通常不是权限错误，也不是回调提前返回，而是它的默认契约：目录里的符号链接不会被跟随。

如果需求是“列出目录项”，保留链接本身即可；如果需求是“处理链接目标”，就要显式解析目标，或者自己实现带循环保护的递归。不要把 d.IsDir() 为 false 当成遍历器坏了。

官方资料：https://pkg.go.dev/path/filepath#WalkDir

接口语义：https://pkg.go.dev/io/fs#WalkDir

先用一棵临时目录树复现问题

最小复现要同时准备真实目录和符号链接：真实目录里放一个嵌套文件，再在扫描根目录下创建一个指向真实目录的链接。回调里打印每个路径、类型和是否为目录，就能看出链接项被访问了，但链接目标没有继续展开。

package main

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

func main() {
	// 使用临时目录隔离复现现场，程序结束后自动清理。
	root, err := os.MkdirTemp("", "walkdir-link-")
	if err != nil {
		panic(err)
	}
	defer os.RemoveAll(root)

	target := filepath.Join(root, "real")
	if err := os.MkdirAll(filepath.Join(target, "nested"), 0o755); err != nil {
		panic(err)
	}
	// 目标目录中的文件用于确认遍历是否真正深入链接目标。
	if err := os.WriteFile(filepath.Join(target, "nested", "data.txt"), []byte("demo"), 0o644); err != nil {
		panic(err)
	}
	link := filepath.Join(root, "link-to-real")
	if err := os.Symlink(target, link); err != nil {
		panic(err)
	}

	err = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		// 回调错误必须显式处理，否则无法区分访问失败和正常边界。
		if err != nil {
			return err
		}
		isLink := d.Type()&fs.ModeSymlink != 0
		fmt.Printf("path=%s isDir=%t isLink=%t\n", path, d.IsDir(), isLink)
		return nil
	})
	if err != nil {
		panic(err)
	}
}

预期观察到的关键关系是：real/nested/data.txt 会被访问，link-to-real 也会被回调，但不会再出现 link-to-real/nested/data.txt。这正是“看到了链接项，却没有遍历链接目标”的最小证据。

为什么回调到了链接，却没有进入链接目标

filepath.WalkDir 的文档明确写着不会跟随符号链接，并且按照词法顺序遍历目录。它把符号链接当作当前目录中的一个条目处理，而不是把条目指向的目录重新挂接到遍历树上。

这里有三个容易混淆的观察点：

还要区分两个 API 的语境。io/fs.WalkDir 的文档特别说明：目录中发现的符号链接不跟随，但如果根路径本身是符号链接，则会遍历其目标。这个例外不应该被套用来推断 filepath.WalkDir 对所有根路径都自动解析；如果根路径可能是链接，先用 EvalSymlinks 得到明确目标，再决定扫描哪个路径。

只读取链接本身，还是先解析真实目标

先把业务意图分成两类，通常就不会误修：

• 备份、索引、清单或权限审计需要保留目录拓扑时，读取链接项本身，并记录它的链接路径。
• 图片收集、源码扫描或资源同步需要处理目标内容时，显式解析目标路径，再把解析结果交给后续逻辑。

读取链接本身时，不要调用会改变语义的 os.Stat 来替代判断。回调收到的 DirEntry 已经足够识别链接；需要目标路径时再调用 filepath.EvalSymlinks。

func describeLink(path string, d fs.DirEntry) error {
	// 先识别链接项，避免把普通文件也送去解析。
	if d.Type()&fs.ModeSymlink == 0 {
		return nil
	}

	// EvalSymlinks 返回清理过的目标路径；悬空链接会在这里返回错误。
	target, err := filepath.EvalSymlinks(path)
	if err != nil {
		return fmt.Errorf("resolve symlink %q: %w", path, err)
	}
	fmt.Printf("link=%s target=%s\n", path, target)
	return nil
}

如果只想把链接保存到清单，可以省略解析步骤；如果解析失败，也应保留原链接路径和错误原因，方便后续区分“悬空链接”和“权限不足”，而不是静默丢弃。

必须深入链接目标时，给递归加上循环保护

符号链接可以形成环：a/next -> ../b，b/next -> ../a。因此不能简单地在 WalkDir 回调里再次调用遍历器，也不能只依赖路径字符串判断是否访问过。更稳妥的做法是每次进入目录前解析真实路径，用 visited 记录已经处理过的目标。

func walkFollowingLinks(path string, visited map[string]bool, visit func(string, fs.FileInfo) error) error {
	// 规范化后再去重，让不同链接路径指向同一目录时只处理一次。
	realPath, err := filepath.EvalSymlinks(path)
	if err != nil {
		return fmt.Errorf("resolve %q: %w", path, err)
	}
	if visited[realPath] {
		return nil
	}
	visited[realPath] = true

	// Stat 会跟随链接，用来判断目标是文件还是目录。
	info, err := os.Stat(path)
	if err != nil {
		return fmt.Errorf("stat %q: %w", path, err)
	}
	if err := visit(path, info); err != nil {
		return err
	}
	if !info.IsDir() {
		return nil
	}

	entries, err := os.ReadDir(path)
	if err != nil {
		return fmt.Errorf("read directory %q: %w", path, err)
	}
	for _, entry := range entries {
		child := filepath.Join(path, entry.Name())
		if err := walkFollowingLinks(child, visited, visit); err != nil {
			return err
		}
	}
	return nil
}

这段代码的重点不是替换标准库，而是把“是否跟随链接”变成显式策略：EvalSymlinks 负责得到目标，visited 负责阻断环路，os.Stat 负责按目标类型判断，os.ReadDir 负责继续展开目录。生产代码还应根据业务需要增加最大深度、允许的根目录和错误策略。

用这张清单定位“没有被遍历”

1. 先看条目类型：打印 d.Type()&fs.ModeSymlink，确认它是否真的是链接。
2. 再看回调错误：err != nil 表示访问当前路径已经出错，不要把它和“不跟随链接”混在一起。
3. 确认目标是否存在：对链接调用 filepath.EvalSymlinks，悬空链接会直接暴露。
4. 确认业务目标：清单任务通常保留链接本身，内容扫描任务才需要进入目标。
5. 确认循环策略：只要允许跟随链接，就必须记录规范化目标或设置深度上限。

在 Unix 系统上创建符号链接通常不需要复制目标内容；在 Windows 上，创建链接可能受权限、开发者模式或目标类型影响。跨平台测试时，应把“链接创建失败”和“遍历不进入链接”当成两类问题分别记录。

结论

filepath.WalkDir 不进入目录中的符号链接，是为了让遍历边界稳定、避免隐式跨目录和环路，而不是遗漏了文件。最小复现应同时打印链接项和真实目录，先确认标准语义；随后根据任务选择保留链接、解析目标，或实现带 visited 保护的显式递归。

相关问题：

• 为什么 DirEntry.Info() 看到的是链接本身而不是目标？
• 悬空符号链接怎样在扫描结果中保留并标记？
• 跟随符号链接时怎样限制最大深度和允许目录？