Go archive/tar Header.Typeflag 区分目录与链接

在 Go 的 archive/tar 中，目录和链接都由一个 tar.Header 描述，区别不在文件名，而在 Header.Typeflag。读取条目时，TypeDir 表示目录，TypeLink 表示硬链接，TypeSymlink 表示符号链接；普通文件则使用 TypeReg。目录和链接主要看元数据，普通文件才按 Header.Size 消费正文数据。

最稳妥的判断顺序是：先检查 Typeflag，再决定是否读取数据；遇到硬链接或符号链接读取 Linkname，不要把它们当作普通文件复制。

Header.Typeflag 的分类关系

Typeflag 是一个字节，常量比直接比较字符更清楚。官方定义中，TypeReg 是普通文件，TypeDir 是目录，TypeLink 和 TypeSymlink 分别是硬链接、符号链接。Typeflag 为零时，写入器会根据名称末尾是否有斜杠，在普通文件和目录之间做默认判断，因此写入目录时应显式使用目录语义，避免只依赖字符串。

目录、链接和普通文件的读取边界

Reader.Next 返回下一个 Header 后，当前条目的数据才可通过同一个 reader 读取。普通文件可以用 io.Copy 复制；目录、硬链接和符号链接没有可供复制的文件正文，调用读取通常直接得到 io.EOF。链接的目标写在 Linkname，不要把目标路径当作当前条目的内容。

package main

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

func describe(tr *tar.Reader) error {
    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            return nil // 没有更多条目，正常结束遍历
        }
        if err != nil {
            return err // 头部损坏或路径策略不接受时保留错误
        }

        switch hdr.Typeflag {
        case tar.TypeDir:
            fmt.Printf("目录: %s\\n", hdr.Name) // 目录只使用元数据
        case tar.TypeLink, tar.TypeSymlink:
            fmt.Printf("链接: %s -> %s\\n", hdr.Name, hdr.Linkname) // Linkname 是目标
        case tar.TypeReg, tar.TypeRegA:
            n, err := io.Copy(io.Discard, tr) // 普通文件才消费正文
            if err != nil {
                return err // 复制失败时停止，避免错位读取下一个条目
            }
            fmt.Printf("文件: %s, %d bytes\\n", hdr.Name, n) // n 应与有效内容长度对应
        default:
            fmt.Printf("其他类型: %s, flag=%q\\n", hdr.Name, hdr.Typeflag) // 保留未知类型供策略处理
        }
    }
}

写入时把类型和目标一起落盘

写入目录或链接时，先填写头部，再调用 WriteHeader；普通文件写完头部后才写正文。目录与链接不要随意设置非零 Size，也不要向它们调用 Write。归档全部完成后必须检查 Close，因为它负责写入填充和尾部，遗漏错误会让输出不完整。

func writeEntry(tw *tar.Writer, hdr *tar.Header, body io.Reader) error {
    if err := tw.WriteHeader(hdr); err != nil {
        return err // 先写元数据，失败时不能继续写正文
    }
    if hdr.Typeflag != tar.TypeReg && hdr.Typeflag != tar.TypeRegA {
        return nil // 目录和链接只有头部，Linkname 已在 hdr 中
    }
    _, err := io.Copy(tw, body) // 普通文件正文长度由 Header.Size 约束
    return err
}

// 使用完 tar.Writer 后检查 Close，确保尾部和填充写入成功。
func finishArchive(tw *tar.Writer) error {
    return tw.Close() // Close 的错误不能被忽略
}

四个容易混淆的边界

• Typeflag 为零：零值不是“未知文件”标签，写入时会结合名称推断普通文件或目录；业务协议最好显式设置。
• Linkname 不是 Name：Name 是归档内条目的名字，Linkname 是链接指向的目标，两者都应按归档路径策略处理。
• PAX 扩展头：读取器会透明处理部分扩展记录，应用层应关注实际条目，不要把内部扩展记录当成业务文件。
• 路径安全：解包前需要拒绝或隔离非本地路径；官方文档说明路径检查与链接目标不是同一件事，不能只检查 Name 就放行所有 Linkname。

相关问题

目录可以读取正文吗？不应把目录当作普通文件读取；它主要由 Name、Mode 和 Typeflag 表示，reader 对这类特殊类型不会提供普通文件正文。

硬链接和符号链接如何区分？分别比较 tar.TypeLink 与 tar.TypeSymlink，两者都看 Linkname，但解包策略必须另行决定是否跟随目标以及如何限制路径。

总结来说，Header.Typeflag 决定“这个条目是什么”，Linkname 描述“链接指向哪里”，Size 决定“普通文件要消费多少数据”。先按类型分流，再处理字段和 reader，目录与链接的判断就不会被普通文件逻辑带偏。