Go filepath.WalkDir 遍历符号链接时为什么不会进入目标目录

用 Go 扫描目录时，如果目录里有一个指向另一个目录的符号链接，filepath.WalkDir 会回调这个链接，却不会继续进入它指向的目标目录。这不是权限异常，而是刻意的遍历边界：链接在 DirEntry 中仍是一个非目录项，遍历器因此不会递归下钻。

想保持目录树边界，就直接使用 WalkDir；想跟随链接，先明确解析目标、处理循环和重复访问，再把解析后的路径交给自己的策略。

一、先用一个小目录复现“不进入目标目录”

假设测试目录如下：真实目录 data 下有 report.txt，同级的 data-link 是指向 data 的符号链接。下面的扫描器只打印每个回调收到的路径和类型。

package main

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

func main() {
    // 只观察目录项本身，不主动解析符号链接的目标。
    err := filepath.WalkDir("demo", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            // 让上层知道哪个路径读取失败，不把错误伪装成空目录。
            return fmt.Errorf("访问 %s: %w", path, err)
        }
        fmt.Printf("%-24s dir=%v type=%v\\n", path, d.IsDir(), d.Type())
        return nil
    })
    if err != nil {
        // 入口错误和中途错误都在这里统一收口。
        panic(err)
    }
}

输出中会出现 demo/data-link，但不会出现 demo/data-link/report.txt。关键不是路径字符串长得像目录，而是回调里的 d.IsDir() 对这个链接返回 false，WalkDir 因而停止在链接这一层。

二、DirEntry 看的是谁：链接本身还是目标目录

DirEntry 描述的是当前路径下读到的目录项。对普通目录，IsDir() 为 true；对符号链接，它反映链接本身的文件类型，而不是跟随链接后目标的文件类型。Type() 也只提供目录项类型位，不能用来替代一次目标解析。

如果只是想把链接列出来，检查 d.Type()&os.ModeSymlink 即可；如果必须知道它最终指向哪里，再调用 EvalSymlinks(path)。不要因为解析结果是目录，就把所有链接无条件重新塞回遍历队列。

三、需要跟随时，先解析再做去重

备份、索引或内容审计有时确实需要跟随链接。此时把它写成单独函数，至少记录原始路径和解析后的路径，并用真实路径去重，避免多个链接重复扫描同一目录。

func resolveLink(path string, d fs.DirEntry) (string, error) {
    // 只有符号链接才跨越目录项边界，普通文件直接返回原路径。
    if d.Type()&os.ModeSymlink == 0 {
        return path, nil
    }
    target, err := filepath.EvalSymlinks(path)
    if err != nil {
        // 断链、权限不足和循环链接都应保留原始错误。
        return "", fmt.Errorf("解析符号链接 %s: %w", path, err)
    }
    return target, nil
}

这个函数只做解析，不负责递归。真正的扫描器还应维护已访问路径集合，并限制允许进入的根目录；否则一个链接既可能造成重复工作，也可能把扫描范围带到预期目录之外。示例中的 os、fmt 和 filepath 需要按实际文件合并 import。

四、常见问题与验收清单

为什么 WalkDir 会打印链接，却不打印链接下面的文件？

因为回调会访问每个目录项，但只有 IsDir() 为 true 的项才继续读取子项；符号链接本身不是目标目录。

Info() 会不会自动跟随符号链接？

不要把它当作遍历开关。需要确认当前项与目标项的差异时，应明确使用适合场景的 Lstat、Stat 或 EvalSymlinks，并处理错误。

怎么确认扫描器没有越过根目录？

对解析后的目标做规范化和根路径校验，再决定是否加入队列；同时记录原始链接路径、目标路径和去重键。

最后按四项检查：是否区分了链接本身与目标、是否保留了 WalkDir 的错误、是否对跟随策略做了去重、是否限制了解析后的根目录。满足这些条件，WalkDir“不进入目标目录”的行为就会从困惑变成可控的安全边界。