Go archive/tar 归档符号链接时怎么控制跟随行为

Go 的 archive/tar 不会自动替你决定“要不要跟随符号链接”。归档时是否读取链接目标，取决于你用 Lstat 还是 Stat，以及遍历目录时是否继续进入链接目录；解包时是否创建链接，则是另一道安全策略。最稳妥的做法是：归档阶段把链接保存为 TypeSymlink + Linkname，解包阶段先校验目标路径，再决定是否调用 os.Symlink。

记住这个边界：普通文件归档的是内容，符号链接归档的是“它指向哪里”这条元数据；archive/tar 负责编码归档项，不负责替你选择文件系统跟随策略。

• 用 os.Lstat 保留链接本身的类型。
• 用 tar.Header.TypeSymlink 和 Linkname 原样记录链接。
• 解包时拒绝绝对目标和逃出目标目录的 .. 路径。

归档时到底保存了什么

tar.Header 的 Typeflag 区分普通文件、目录和符号链接。符号链接的目标放在 Linkname，它不是一个需要由 tar.Writer 再打开的文件名。也就是说，读取链接目标内容并不是 tar 写入的默认动作。

图1：普通文件写入内容，符号链接只写 TypeSymlink 与 Linkname。

最容易出错的地方在文件信息获取：os.Stat 会沿着链接得到目标信息，而 os.Lstat 返回链接自身的信息。归档链接时先用后者，再用 os.Readlink 取得目标字符串。

用 WalkDir 和 Header 明确控制跟随

下面的小实验创建一个普通文件和一个指向它的链接。遍历器遇到链接时只写一条链接头，不打开目标，也不递归进入链接目录；普通文件才复制内容。

package main

import (
    "archive/tar"
    "fmt"
    "io"
    "os"
    "path/filepath"
    "strings"
)

func addPath(tw *tar.Writer, root, path string, d os.DirEntry) error {
    rel, err := filepath.Rel(root, path)
    if err != nil { return err }
    rel = filepath.ToSlash(rel)
    info, err := d.Info() // DirEntry.Info 保留当前条目的类型判断
    if err != nil { return err }
    if info.Mode()&os.ModeSymlink != 0 {
        target, err := os.Readlink(path) // 只读链接文字，不打开目标文件
        if err != nil { return err }
        h, err := tar.FileInfoHeader(info, target)
        if err != nil { return err }
        h.Name, h.Typeflag, h.Size = rel, tar.TypeSymlink, 0
        return tw.WriteHeader(h) // 符号链接是 header-only 归档项
    }
    h, err := tar.FileInfoHeader(info, "")
    if err != nil { return err }
    h.Name = rel
    if err := tw.WriteHeader(h); err != nil { return err }
    if !info.Mode().IsRegular() { return nil }
    f, err := os.Open(path)
    if err != nil { return err }
    defer f.Close() // 只为普通文件打开内容流
    _, err = io.Copy(tw, f)
    return err
}

func main() {
    root := "demo-tar-root"
    _ = os.RemoveAll(root) // 实验目录可重复运行
    if err := os.MkdirAll(root, 0755); err != nil { panic(err) }
    if err := os.WriteFile(filepath.Join(root, "config.txt"), []byte("mode=demo\n"), 0644); err != nil { panic(err) }
    if err := os.Symlink("config.txt", filepath.Join(root, "current")); err != nil { panic(err) }

    out, err := os.Create("links.tar")
    if err != nil { panic(err) }
    tw := tar.NewWriter(out)
    err = filepath.WalkDir(root, func(path string, d os.DirEntry, walkErr error) error {
        if walkErr != nil { return walkErr }
        if path == root { return nil }
        return addPath(tw, root, path, d) // 链接只写元数据，绝不跟随递归
    })
    if err == nil { err = tw.Close() }
    if closeErr := out.Close(); err == nil { err = closeErr }
    if err != nil { panic(err) }
    fmt.Println(strings.TrimSpace("links.tar created"))
}

检查归档时，不要把 Reader.Read 的行为套到所有类型上：官方文档明确说明，读到 TypeSymlink 等 header-only 类型时会直接得到 io.EOF。判断链接应看 Header.Typeflag 和 Header.Linkname。

解包时要单独设安全边界

归档时保留链接，不等于解包时必须创建链接。未知归档可能带有绝对目标，或者通过 ../ 指向目标目录外。先把归档项名称和链接目标都解析为目标目录下的路径，只允许结果仍位于目标目录内。

图2：解包先校验 Linkname 是否留在目标目录内，再决定是否创建符号链接。

func safeLinkPath(root, name, linkname string) (string, string, error) {
    cleanName := filepath.Clean(filepath.FromSlash(name))
    cleanTarget := filepath.Clean(filepath.FromSlash(linkname))
    if filepath.IsAbs(cleanTarget) || cleanTarget == "." { // 绝对目标不落入归档目录
        return "", "", fmt.Errorf("拒绝不安全链接目标: %q", linkname)
    }
    linkPath := filepath.Join(root, cleanName)
    targetPath := filepath.Join(filepath.Dir(linkPath), cleanTarget)
    rel, err := filepath.Rel(root, targetPath)
    if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", "", fmt.Errorf("链接目标越出目录: %q", linkname)
    }
    return linkPath, targetPath, nil
}

// 只有 safeLinkPath 返回成功后，才可以在目标目录内创建链接。
func createSafeLink(root string, h *tar.Header) error {
    linkPath, targetPath, err := safeLinkPath(root, h.Name, h.Linkname)
    if err != nil { return err }
    if err := os.MkdirAll(filepath.Dir(linkPath), 0755); err != nil { return err }
    return os.Symlink(filepath.Base(targetPath), linkPath) // 保存相对目标，避免扩大范围
}

这个校验保护的是解包写入边界，不是归档格式本身。生产代码还应处理重复文件名、已有路径、权限和跨平台差异；若业务不需要恢复链接，可以直接跳过 TypeSymlink，将它记录到审计日志。

常见误区和最终检查

第一，不能用“字符串看起来像链接”代替文件类型判断；第二，不能因为用了 WalkDir 就省略解包校验；第三，不能给符号链接头写入目标文件字节。发布前可以按这张表快速核对：

相关问题

为什么归档后读取链接得到空内容？ 因为链接项是 header-only 类型，目标在 Linkname，不是数据体。

能不能把链接目标文件内容也打进 tar？ 可以，但那是把条目按普通文件处理的另一种业务规则；它会丢失“这是链接”的语义，不能与原样恢复链接混用。

参考：Go archive/tar 文档、filepath.WalkDir 文档、os.Lstat 文档。