Go archive/tar 怎么读取归档头

读取 tar 文件时，真正要先拿到的不是正文，而是当前条目的归档头。Go 标准库的 archive/tar 用 tar.NewReader 创建读取器，再反复调用 Next()；每次返回一个 *tar.Header，从中可以取得文件名、大小、类型、权限和时间。确认条目是普通文件后，才把当前正文交给 io.Copy 或其他写入器。

先把 tar 输入变成可遍历的 Reader

archive/tar 不要求输入一定来自磁盘文件，只要实现了 io.Reader 就可以读取。因此本地文件、内存缓冲区、网络响应体都能走同一条解析路径。文件句柄用完要关闭，解析器则负责按 tar 条目的边界推进。

package main

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

func listHeaders(path string) error {
    // 打开 tar 输入；文件句柄只负责提供连续字节流。
    file, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("open tar: %w", err)
    }
    defer file.Close() // 函数结束时释放文件描述符。

    reader := tar.NewReader(file)
    for {
        header, err := reader.Next()
        if err == io.EOF {
            // 没有更多条目是正常结束，不要把它当成失败。
            return nil
        }
        if err != nil {
            return fmt.Errorf("read tar header: %w", err)
        }

        // 这里先只读取元数据，正文仍留在 reader 的当前位置。
        fmt.Printf("name=%q size=%d type=%q mode=%o modtime=%s format=%s\n",
            header.Name, header.Size, header.Typeflag,
            header.Mode, header.ModTime.Format("2006-01-02 15:04:05"),
            header.Format)
    }
}

这段函数的关键是“Next 读取头，reader 读取当前条目正文”。如果上一条正文没有读完，下一次 Next 会自动丢弃当前条目的剩余数据和填充区，所以不要再自己按 512 字节猜边界。

调用 Next 读取当前归档头

Header 可以看成当前条目的身份证：Name 是归档内名称，Size 是正文长度，Typeflag 区分普通文件、目录、链接等类型，Mode 和 ModTime 用于保留权限与时间信息，Format 则是读取器对格式的尽力判断。

读取归档头时，先记录这些字段，再决定是否读取正文。若文章只是做目录索引，读到 Header 后可以直接进入下一轮；若要转换内容，才在同一轮中消费当前条目的数据。

按条目类型处理正文

最容易出错的地方是把每个条目都当成有正文的普通文件。目录通常只需要创建目录或记录名称；普通文件才适合复制正文；符号链接、硬链接和设备条目则应根据业务策略单独处理。下面的例子只把普通文件转换到写入器，并把目录明确跳过。

func copyRegularEntries(input io.Reader, output io.Writer) error {
    // Reader 会根据每个 Header.Size 限制当前条目的可读范围。
    reader := tar.NewReader(input)
    for {
        header, err := reader.Next()
        if err == io.EOF {
            return nil // 归档正常结束。
        }
        if err != nil {
            return fmt.Errorf("next tar entry: %w", err)
        }

        switch header.Typeflag {
        case tar.TypeDir:
            // 目录没有需要复制的正文，保留名称即可。
            continue
        case tar.TypeReg, tar.TypeRegA:
            // 只在普通文件分支消费正文，io.Copy 会读到当前条目结束。
            if _, err := io.Copy(output, reader); err != nil {
                return fmt.Errorf("copy %q: %w", header.Name, err)
            }
        default:
            // 链接和特殊文件不在本例的转换范围内。
            continue
        }
    }
}

示例里的 output 可以是另一个文件、缓冲区或哈希计算器。要分别保存多个归档条目时，应该在每个 Next 后按 header.Name 创建对应的目标写入器，而不是把所有正文无条件拼成一个文件。

处理 EOF、格式错误和路径边界

错误处理可以先分成三类：io.EOF 表示归档结束；tar.ErrHeader 等解析错误表示输入可能损坏或格式不被接受；复制阶段的错误则来自底层输入或输出。不要用“读到任何错误就结束”的写法，否则坏包会被误报成成功。

如果要把条目写入磁盘，Header.Name 不能直接与输出根目录拼接。当前官方文档还说明，在 GODEBUG=tarinsecurepath=0 时，遇到非本地名称，Next 会返回带有 tar.ErrInsecurePath 的 Header。生产代码应先拒绝绝对路径、父目录跳转和不符合业务规则的名称，再决定是否创建文件；链接目标也要单独制定策略。

常见问题

1. 只想列出文件名，需要读取正文吗？

不需要。每次 Next() 成功后读取 Header.Name 等字段即可；下一次 Next() 会推进到下一个条目。

2. 为什么目录也能拿到 Header？

tar 的每个条目都先以 Header 描述，目录只是 Typeflag 不同。它通常没有要复制的正文，所以应在目录分支跳过。

3. 读取一个条目后忘记 io.Copy 会卡在下一个条目吗？

不会。Next() 会自动丢弃当前条目的未读部分，但显式读取正文仍有助于完成转换、校验或统计，逻辑更清楚。

4. Header.Size 是整个 tar 文件大小吗？

不是。它只描述当前条目的正文大小；整个归档由多个 Header、正文和格式填充区组成。

把流程记成一句话即可：先用 Next 拿 Header，再按 Typeflag 决定如何读取当前正文，最后把 io.EOF 当作正常结束，并在落盘前检查归档名称。