Go filepath.WalkDir 如何控制符号链接

用 Go 遍历上传目录、缓存目录时，符号链接最容易让结果和预期不一样：链接看起来像一个目录，但 filepath.WalkDir 默认不会沿着它进入目标目录。它会把链接作为一个目录项交给回调，之后停止向链接目标展开。工程上通常应该在回调里识别并记录或跳过它；如果业务确实要跟随，也要把解析目标、去重和允许范围写成单独策略。

一句话记忆：filepath.WalkDir 负责发现链接，不负责替你跟随链接。用 DirEntry.Type() 或 Info() 判断链接，再决定跳过、告警，还是解析后进行一次受控遍历。

先把 filepath.WalkDir 的符号链接规则说清楚

filepath.WalkDir(root, fn) 会从 root 开始回调每个文件或目录，访问顺序是字典序，因此同一棵目录树的输出具有确定性。它与旧的 filepath.Walk 一样不跟随符号链接，但使用 fs.DirEntry，避免对每个条目都先做一次完整的 os.Lstat。

因此，假设 data/latest 是指向 /srv/archive 的链接，遍历 data 时可以收到 data/latest 这个条目；但回调不会继续收到 /srv/archive 下的文件。这个边界适合清理、统计、打包等默认不应扩大扫描范围的任务。

在回调里识别链接，再决定是否跳过

最小做法是先处理回调错误，再判断 DirEntry 的类型。不要在 err != nil 时直接访问 d，因为访问根路径或某个条目失败时，d 可能为空。

package main

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

func main() {
    root := "./data"

    err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        // 先处理访问错误，避免 d 为空时继续读取类型。
        if err != nil {
            return fmt.Errorf("访问 %s 失败: %w", path, err)
        }

        // Type 返回目录项的类型位；符号链接本身不是目标目录。
        if d.Type()&os.ModeSymlink != 0 {
            fmt.Printf("跳过符号链接: %s\n", path)
            return nil
        }

        // 只对真实目录和文件执行后续业务逻辑。
        fmt.Println("处理:", path)
        return nil
    })
    if err != nil {
        // WalkDir 返回的错误保留给上层，便于任务失败时重试或告警。
        fmt.Println("遍历失败:", err)
    }
}

这里返回 nil 只是忽略这个链接条目，并不是让遍历器跟随它。若发现的是不应继续展开的真实目录，才使用 filepath.SkipDir；对普通文件返回 SkipDir 会跳过它的父目录，语义并不相同。

需要跟随时，把解析和遍历拆成两层

有些备份索引或媒体目录确实要求纳入链接目标。此时不要把 filepath.WalkDir 当成“自动跟随开关”，而应在识别链接后调用 filepath.EvalSymlinks 得到目标，再启动一次独立遍历。

独立遍历前至少做三项控制：第一，限制目标必须落在业务允许的根路径内；第二，用规范化后的目标路径或文件系统标识去重；第三，对链接回指、交叉链接和重复挂载设置访问记录。否则“目录不重复”并不等于“目标不重复”，也可能把整台机器的其他路径纳入扫描。

// 仅展示跟随策略的关键分支，不把链接目标当作默认遍历结果。
func resolveLink(path, allowedRoot string) (string, error) {
    target, err := filepath.EvalSymlinks(path)
    if err != nil {
        return "", fmt.Errorf("解析符号链接失败: %w", err)
    }

    // Clean 只做词法整理，真实范围判断仍需使用已解析的目标路径。
    relative, err := filepath.Rel(allowedRoot, target)
    if err != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(os.PathSeparator)) {
        return "", fmt.Errorf("链接目标超出允许范围: %s", target)
    }
    return target, nil
}

上面代码片段需要额外导入 strings；它只表达范围判断的关键位置。生产代码还应按平台处理大小写、挂载点和并发访问，并把已访问目标放入集合，避免循环链接。

Walk、WalkDir 和 fs.WalkDir 怎么选

新写的本地目录遍历通常优先考虑 filepath.WalkDir。如果代码要同时处理嵌入文件、压缩包或自定义 fs.FS，则 fs.WalkDir 的统一接口更合适。无论选哪个 API，都不要用“是否看到目标文件”反推链接一定被跟随，最好在回调里明确记录类型与策略。

常见问题

filepath.WalkDir 能递归遍历符号链接目录吗？不能。它会访问链接这个目录项，但不会把链接目标当作当前树的子目录继续递归。

什么时候调用 DirEntry.Info()？只在需要大小、修改时间或完整模式信息时调用。对于符号链接，官方语义是返回链接自身的信息，而不是目标的信息。

返回 filepath.SkipDir 能让链接目标展开吗？不能。SkipDir 是跳过当前真实目录的控制值，不是跟随链接的开关；链接跟随需要显式解析和单独的安全边界。

官方事实可参考：https://pkg.go.dev/path/filepath#WalkDir 与 https://pkg.go.dev/io/fs#WalkDir。