Go os CopyFS 复制符号链接失败怎么办

使用 os.CopyFS 复制目录时，如果源文件树里有符号链接，失败通常不是“CopyFS 不支持链接”，而是源文件系统没有提供读取链接目标的能力，或者目标位置无法重新创建链接。先确认复制语义，再按错误类型处理，问题就不会被误判成普通文件读写失败。

官方地址：https://pkg.go.dev/os@go1.27.3#CopyFS

CopyFS 会保留源符号链接：遍历到链接后调用 fs.ReadLink，再用 os.Symlink 在目标目录创建同名链接。自定义 fs.FS 只实现了 Open 还不够，必须实现 fs.ReadLinkFS，否则很容易得到 fs.ErrInvalid。

CopyFS 为什么不是把链接目标读成普通文件

os.CopyFS(dir, fsys) 通过 fs.WalkDir 遍历源文件树。普通文件会被打开并复制内容；目录会创建目录；遇到 fs.ModeSymlink 时，则读取链接目标字符串，然后在目标位置重新创建符号链接。因此，目标目录中的结果仍然是链接，不是目标文件的副本。

这也是排查的第一个分界点：如果业务想要“保留链接关系”，就要让源 FS 能读链接；如果业务想要“只复制最终内容”，就不能把 CopyFS 的默认行为当成解引用复制。下面的图是静态结构说明，不是某次运行的截图或运行证据。

先检查源 FS 是否实现 ReadLinkFS

io/fs 把符号链接能力单独定义为 fs.ReadLinkFS。这个接口除了 ReadLink，还要求提供不跟随链接的 Lstat。fs.ReadLink(fsys, name) 在发现 fsys 没有实现该接口时，会返回包装了 fs.ErrInvalid 的错误。

package main

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

// copyWithLinks 要求源文件系统明确支持读取符号链接。
func copyWithLinks(dst, src string) error {
    source := os.DirFS(src)

    // 只有实现 ReadLinkFS，CopyFS 才能保留源链接目标。
    if _, ok := source.(fs.ReadLinkFS); !ok {
        return fmt.Errorf("source FS does not implement fs.ReadLinkFS")
    }

    // CopyFS 会创建目标目录，并且不会覆盖已有文件。
    if err := os.CopyFS(dst, source); err != nil {
        return fmt.Errorf("copy directory with links: %w", err)
    }
    return nil
}

这里的类型断言是提前给出清晰错误，不是额外的内容校验。对于自定义文件系统，修复方向是让同一个实现同时满足 fs.FS 和 fs.ReadLinkFS：ReadLink 返回链接本身保存的相对或绝对目标字符串，Lstat 返回链接的类型信息，而不是把链接目标的类型冒充成普通文件。

把三类失败分开看

复制符号链接时，错误位置不同，修复动作也不同。可以用下面的静态关系来记忆：源 FS 负责提供链接信息，目标文件系统负责创建链接，业务代码负责决定哪些错误可以降级。

package main

import (
    "errors"
    "fmt"
    "io/fs"
)

// explainCopyError 只做错误分类，是否重试仍由上层业务决定。
func explainCopyError(err error) error {
    // ErrInvalid 通常指向源 FS 的链接能力缺失。
    if errors.Is(err, fs.ErrInvalid) {
        return fmt.Errorf("source symlink metadata is unavailable: %w", err)
    }

    // ErrExist 表示 CopyFS 不覆盖目标中的已有条目。
    if errors.Is(err, fs.ErrExist) {
        return fmt.Errorf("destination entry already exists: %w", err)
    }

    // 其他错误保留原始包装，便于识别系统权限或路径问题。
    return fmt.Errorf("copy failed: %w", err)
}

别把保留链接和复制内容混在一起

如果配置目录中的链接表达了共享文件、相对路径或部署布局，正确目标是保留链接关系，应该修复 ReadLinkFS 或源 FS 的实现。如果归档格式明确要求所有条目都是普通文件，才应该在业务层设计“解引用后复制内容”的策略；那已经不是 CopyFS 默认的符号链接语义，不能只通过忽略错误来实现。

还要记住两个边界：第一，CopyFS 不覆盖目标中已经存在的同名条目；第二，目标目录中的符号链接会被跟随，目标路径规划不当时可能把创建动作带到另一个目录。复制前应给出空的、明确的目标根目录，并把错误原样保留在日志或返回值中。

常见问题

只实现 fs.FS，为什么普通文件能复制，符号链接却失败？

普通文件只需要通过 Open 读取内容；符号链接需要读取链接本身的目标字符串。CopyFS 对链接分支调用的是 fs.ReadLink，因此需要额外的 fs.ReadLinkFS 能力。

把符号链接改成普通文件就一定能复制吗？

不一定。那会改变复制语义，而且目标已有路径、权限、路径有效性等问题仍可能存在。先确定业务是保留链接还是复制目标内容，再选择对应实现。

总结：排查 os.CopyFS 的符号链接失败，先看源 FS 是否实现 fs.ReadLinkFS，再区分目标冲突和系统创建权限。不要把“无法读取链接元数据”误当成普通文件不存在，也不要用静默降级掩盖复制语义变化。