Go 遍历符号链接时为什么不会自动进入目标目录

做目录扫描时，最容易误判的一幕是：根目录里明明有一个指向共享目录的符号链接，filepath.WalkDir 却只回调了这个链接的路径，没有继续列出目标目录里的文件。这个结果是正常行为，不是遍历漏了数据。

结论很简单：filepath.WalkDir 会访问符号链接这个目录项，但不会跟随它进入目标目录。用 DirEntry.Type() 识别链接，用 os.Stat(path) 显式读取目标；访问失败则从回调的 err 参数记录和处理。

先确认 WalkDir 看到的是哪一个对象

WalkDir 的回调参数里，path 是当前路径，d 是该路径对应的目录项。符号链接首先是一个目录项，所以它会被回调看到；但它的类型位是 os.ModeSymlink，不是目标目录的类型。也就是说，d.IsDir() 不应被用来推断“链接指向的对象是不是目录”。

这个边界也解释了为什么链接下方没有子项：遍历器只把根目录的直接目录项交给回调，发现该项是链接后不会替它打开并递归。目录树里可能同时出现真实目录 assets 和链接 public-assets，两者在回调中的语义不同。

用 os.Stat 显式确认符号链接的目标

如果业务确实要知道链接指向的是文件还是目录，先确认链接，再显式解析目标。os.Stat 会沿着符号链接取得目标信息；而 d.Info() 的职责仍然是描述当前目录项。想记录链接文字本身时，可以额外调用 os.Readlink。

package main

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

func scan(root string) error {
    return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        // 访问当前项失败时保留路径；这里选择跳过该项继续扫描兄弟项。
        if err != nil {
            fmt.Printf("无法访问 %s：%v\n", path, err)
            return nil
        }

        // 先判断目录项本身，不能用 IsDir 猜测链接目标。
        if d.Type()&os.ModeSymlink != 0 {
            target, statErr := os.Stat(path) // Stat 显式跟随链接读取目标信息。
            if statErr != nil {
                fmt.Printf("失效或不可访问的链接 %s：%v\n", path, statErr)
                return nil
            }
            linkText, linkErr := os.Readlink(path) // Readlink 只读取链接文字。
            if linkErr != nil {
                return fmt.Errorf("读取链接 %s：%w", path, linkErr)
            }
            fmt.Printf("链接 %s -> %s，目标目录=%t\n", path, linkText, target.IsDir())
            return nil
        }

        // 只对真实目录做过滤，避免把符号链接当成可递归目录。
        if d.IsDir() && d.Name() == ".cache" {
            return fs.SkipDir
        }
        if !d.IsDir() {
            fmt.Println("文件：", path)
        }
        return nil
    })
}

这里的 Stat 和 Readlink 故意分成两件事：前者回答目标对象的属性，后者回答链接里保存的路径文字。若目标已被删除，Stat 会失败，但链接项本身仍可能被 WalkDir 回调到，这正是记录断链的机会。

把权限错误、断链和过滤规则分开处理

WalkDir 发现某个文件或目录无法访问时，会把错误传给回调；此时 d 可能为空，所以必须先判断 err。上例选择打印后返回 nil，适合“尽量扫描完整并汇总异常”的任务。如果权限错误意味着结果不可用，则应返回原错误，让遍历立即结束。

fs.SkipDir 只用于“不要进入这个真实目录”的过滤决定，例如缓存目录、临时目录或租户隔离目录。对一个普通文件返回它会跳过其所在目录的剩余项，因此不要把它当作通用的“忽略当前项”标记。符号链接不需要用 SkipDir 阻止递归，因为 WalkDir 本身已经不跟随它。

上线前用四项检查解释扫描结果

当扫描结果比预期少时，先不要把 WalkDir 改成自定义递归。可以按下面清单判断缺项来自哪里：

如果产品要求“跟随链接并继续递归”，那已经超出 WalkDir 默认语义，需要单独设计：限制允许的根目录，记录已解析目标，检测循环并定义权限失败策略。不要只把 os.Stat 塞进回调后再次调用 WalkDir，否则很容易重复扫描同一目录或越过原本的边界。

相关问题

WalkDir 和 Walk 都会跟随符号链接吗？

不会。两者都不跟随符号链接；WalkDir 只是使用 fs.DirEntry，并减少了部分文件信息调用。

d.Info() 能直接拿到链接目标的大小吗？

不能把它当成目标信息。对符号链接，d.Info() 描述链接本身；目标大小应通过 os.Stat(path) 取得。

遇到权限错误应该返回 nil 还是原错误？

取决于结果要求：汇总式扫描可记录后继续，必须完整可信的索引则返回错误并让上层重试或报警。

为什么不直接把每个链接当成目录跳过？

因为链接可能指向文件，也可能已经断开。先识别链接，再用 Stat 和 Readlink 分别确认目标属性与链接文字，日志才有诊断价值。

参考：filepath.WalkDir、io/fs.DirEntry、os.Stat、os.Readlink。