Go archive/tar识别 Tar 硬链接与符号链接的排查指南

排查 Tar 中的硬链接和符号链接，关键不是看文件名有没有后缀，而是读取 archive/tar.Header 的类型标志。TypeLink（值为 '1'）表示硬链接，TypeSymlink（值为 '2'）表示符号链接；两者的目标都放在 Header.Linkname 中，条目本身没有普通文件正文。

因此，Go 代码应让 Reader.Next 负责推进条目，用 Typeflag 做分类，用 Name 记录归档内名称，用 Linkname 记录目标。只有普通文件才进入正文复制逻辑；至于是否跟随链接、是否落盘，要由解包程序自己的路径和权限策略决定。

先看 Header 的三组字段

一个 Tar 条目可以先抽象成“条目名称、类型、链接目标”三组信息。Name 是归档中当前条目的名字，Typeflag 说明它是普通文件、目录还是链接，Linkname 只对硬链接和符号链接有意义。不要把 Linkname 当成当前文件名，也不要因为目标文件尚未出现就立即判定归档损坏。

用 Typeflag 区分硬链接和符号链接

可靠判断应直接比较常量，而不是猜测压缩包来自哪个系统。硬链接和符号链接都属于头部标志，但语义不同：硬链接通常把目标理解为归档中的另一个文件名，符号链接则保存一个链接路径。archive/tar 只负责呈现这个元数据，不替应用决定如何解析目标。

package main

import (
	"archive/tar"
	"fmt"
	"io"
)

func inspectEntries(r io.Reader) error {
	tr := tar.NewReader(r)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			return nil // 到达归档尾部，排查正常结束。
		}
		if err != nil {
			return fmt.Errorf("读取 Tar 条目失败: %w", err) // 保留原始错误便于定位损坏头部。
		}

		switch hdr.Typeflag {
		case tar.TypeLink:
			fmt.Printf("hard-link name=%q target=%q\n", hdr.Name, hdr.Linkname) // 硬链接只登记目标。
		case tar.TypeSymlink:
			fmt.Printf("symlink name=%q target=%q\n", hdr.Name, hdr.Linkname) // 符号链接也只登记目标。
		default:
			fmt.Printf("entry name=%q type=%q size=%d\n", hdr.Name, hdr.Typeflag, hdr.Size) // 普通条目保留大小。
			if _, err := io.Copy(io.Discard, tr); err != nil {
				return fmt.Errorf("消费 %q 的正文失败: %w", hdr.Name, err) // 只对有正文的条目消费 Reader。
			}
		}
	}
}

这里没有调用本地解压，也没有把链接目标转换成操作系统链接。这个函数的结果只是诊断记录：它能说明归档声明了什么，不能说明目标在磁盘上一定存在。

链接条目不要按普通文件读取

官方接口把链接视为 header-only 类型。对 TypeLink、TypeSymlink 调用 Reader.Read 时不会得到普通文件内容；正确做法是读取 Linkname 后继续 Next。对普通文件，Next 会根据当前条目的 Header.Size 管理可读范围，未消费完的剩余数据也会在下一次 Next 时被丢弃。

排查时可以维护一个按 Header.Name 建立的集合，并把链接目标另存为关系字段。目标先出现、后出现或根本没有同名条目，都应作为不同状态记录；不要用“目标未出现”替代“链接类型错误”。

把路径策略和链接识别分开

识别链接只是第一层。若程序随后要解包到磁盘，还应明确是否允许链接、目标是否必须位于目标目录内、重复名称如何处理，以及是否先建立普通文件再建立链接。archive/tar 的路径安全提示主要针对条目名称；不能因为名称通过检查，就认为 Linkname 自动安全，更不能默认跟随它写盘。

• 看见 TypeLink 或 TypeSymlink：读取并原样记录 Linkname。
• 看见普通文件或目录：按对应类型处理，不把缺少 Linkname 当成错误。
• 遇到未知类型：保留 Typeflag 和 Name，交给上层策略，不静默改成普通文件。

常见排查问题

为什么不能用 Name 的后缀判断符号链接？

因为链接语义存放在 Tar 头部的 Typeflag，文件名只是条目名称，改名后类型仍然不变。

硬链接和符号链接都要读取 Linkname 吗？

要。两类链接都由 Header.Linkname 描述目标，但目标解析和落盘策略不能混为一谈。

链接条目需要调用 io.Copy 吗？

不需要。链接是 header-only 条目；调用 Next 读取下一个头部即可，正文复制逻辑只给普通文件使用。