Go archive/tar Reader.Next 如何识别目录和链接

遍历 tar 归档时，Reader.Next 不会直接返回“这是目录”或“这是链接”的字符串。正确做法是读取它返回的 *tar.Header，用 Header.Typeflag 判断类型：TypeDir 是目录，TypeSymlink 是符号链接，TypeLink 是硬链接；链接目标再从 Linkname 读取。普通文件才适合继续调用 Read 取内容。

一句话记忆：Name 是归档条目的名字，Typeflag 决定它是什么，Linkname 只在链接条目上表示目标。

官方参考：https://pkg.go.dev/archive/tar

一、先用 Typeflag 判断条目类型

不要把“名称以 / 结尾”当成唯一依据。tar 格式的类型信息位于头部，Go 将它暴露为 Header.Typeflag。目录、符号链接和硬链接都可能没有可读取的数据体，因此先分型，再决定后续动作。

较老的归档可能用普通文件类型加尾部斜杠表示目录，archive/tar 在读取时会兼容这种情况。应用层仍应以返回头部的类型常量为准，而不是自己重复猜测。

二、用 Name 和 Linkname 读取识别结果

识别类型后，字段的职责就很清楚：Name 是当前归档项的路径名；当类型是硬链接或符号链接时，Linkname 是目标名。目标名不是文件内容，也不等于已经在操作系统中解析完成的真实路径。

package main

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

func describeTar(tr *tar.Reader) error {
    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            // 归档自然结束，不把 io.EOF 当成失败。
            return nil
        }
        if err != nil {
            // 头部损坏或路径错误需要交给调用方决定是否中止。
            return fmt.Errorf("读取 tar 头部失败: %w", err)
        }

        switch hdr.Typeflag {
        case tar.TypeDir:
            fmt.Printf("目录: %s\n", hdr.Name)
        case tar.TypeSymlink:
            fmt.Printf("符号链接: %s -> %s\n", hdr.Name, hdr.Linkname)
        case tar.TypeLink:
            fmt.Printf("硬链接: %s -> %s\n", hdr.Name, hdr.Linkname)
        default:
            // 普通文件等可读取类型只先记录名称，数据由后续逻辑消费。
            fmt.Printf("其他条目: %s (type=%q)\n", hdr.Name, hdr.Typeflag)
        }
    }
}

这里的函数只负责识别和打印，调用 Next 后没有对链接执行 Read。如果你的代码要解包，目录可以创建，普通文件可以写入；链接是否创建以及目标是否允许，应该是另一层策略。

三、在 Next 循环中处理数据和结束条件

Next 每成功调用一次，就把 Reader 定位到下一个归档项。当前普通文件还有未读字节时，下一次 Next 会自动丢弃剩余数据和填充块，所以不需要为了“跳过文件”手写额外的读取循环。

真正需要读取内容时，把 Read 放在普通文件分支中：

if hdr.Typeflag == tar.TypeReg {
    // 只消费普通文件的数据，避免把链接或目录当成文件复制。
    n, err := io.Copy(dst, tr)
    if err != nil {
        return fmt.Errorf("复制 %s 失败: %w", hdr.Name, err)
    }
    fmt.Printf("写入 %s，共 %d 字节\n", hdr.Name, n)
}

遍历结束只认 io.EOF。其他错误不能静默跳过；例如启用 GODEBUG=tarinsecurepath=0 时，遇到非本地文件名可能返回带有 ErrInsecurePath 的结果。是否兼容这类路径，应由解包程序明确决定。

四、把路径安全和链接落地分开

Next 的路径检查主要针对条目的 Name，官方文档明确说明不会替应用验证链接目标。因此即使 hdr.Name 看起来安全，也不要直接把 hdr.Linkname 拼到输出目录后创建链接。

实用的处理顺序是：先用 filepath.IsLocal(hdr.Name) 检查归档项名称；普通文件和目录再将清理后的路径限制在目标目录内；链接则额外检查目标是否允许、是否会跳出目标目录，以及业务是否真的需要保留链接。若只是读取归档清单，记录 Name 和 Linkname 通常比立即落地更稳妥。

还要注意，Header.Size 表示普通文件可读的字节数。对目录、硬链接、符号链接等特殊类型调用 Read，会得到文件结束，而不是链接目标的内容。把“识别链接”和“解析链接”拆开，能避免误写文件或产生路径穿越风险。

相关问题

Reader.Next 返回的 Header.Name 一定带完整目录路径吗？

它表示归档中记录的条目名，可能包含目录层级，但不能把它当成可信的本地绝对路径。落地前仍需做本地路径检查和输出目录约束。

符号链接的目标内容能直接从 tar.Reader 读出来吗？

不能。符号链接目标在 Linkname 中，Reader 不会替你跟随目标读取内容；是否跟随以及如何限制目标，要由解包逻辑单独实现。

为什么遍历 tar 时最后会出现 io.EOF？

这是正常结束信号。把 io.EOF 与头部损坏、路径不安全等真实错误分开处理即可。

小结：先看 Typeflag，再按类型读取 Name 或 Linkname；普通文件才消费 Reader 数据；最后把条目名检查与链接目标安全策略分成两步。