Go archive/tar 怎样处理 tar Reader 的截断输入

用 Go 的 archive/tar 读压缩包时，最容易误判的是把“当前文件读完”和“整个归档正常结束”混成一件事。判断是否安全完成，关键看错误发生在什么位置：当前条目的正文短于 Header.Size 时，应得到 io.ErrUnexpectedEOF；所有条目都完成并读到归档结束标记时，Reader.Next 才返回 io.EOF。

因此，处理截断输入的核心不是重新猜文件大小，而是在 Next 和正文复制两个位置都保留错误上下文。遇到 io.ErrUnexpectedEOF 就停止把结果交给后续业务，并记录当前条目名称。

先明确 Reader 的错误边界

tar.NewReader 只接收一个 io.Reader，它可以来自文件、HTTP 响应或管道。Reader.Next 负责推进到下一个条目，返回的 *tar.Header 中的 Size 表示当前条目的逻辑字节数；返回头之后，Reader 本身就代表当前条目的正文。

可以先把三种结果分开记住：

尤其要注意：io.EOF 出现在某个条目的 Read 结束位置时，只表示这个条目的逻辑数据已经读完；它不等于整个归档结束。只有下一次调用 Next 返回 io.EOF，才是遍历结束。

按条目读取并保留文件名

最稳妥的循环是先拿到 Header，再把当前条目复制到目标输出。这样一旦正文读取失败，日志或上层错误中仍然有 Header.Name，不会只剩一个无法定位的 EOF。

package main

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

func extractTar(r io.Reader, dstDir string) error {
	tr := tar.NewReader(r)

	for {
		hdr, err := tr.Next()
		if errors.Is(err, io.EOF) {
			// Next 返回 EOF 才表示整个 tar 归档遍历完成。
			return nil
		}
		if err != nil {
			// 头部或前一个条目的填充被截断时，错误会在这里出现。
			if errors.Is(err, io.ErrUnexpectedEOF) {
				return fmt.Errorf("读取 tar 头部时归档被截断: %w", err)
			}
			return fmt.Errorf("读取 tar 条目失败: %w", err)
		}

		if hdr.Typeflag != tar.TypeReg {
			// 这里只演示普通文件；目录、链接等类型按业务策略处理。
			continue
		}

		out, err := os.CreateTemp(dstDir, "tar-entry-*")
		if err != nil {
			return fmt.Errorf("创建 %q 的临时文件失败: %w", hdr.Name, err)
		}

		_, copyErr := io.Copy(out, tr)
		closeErr := out.Close()
		if copyErr != nil {
			// Reader 会把正文不足 Header.Size 映射成 ErrUnexpectedEOF。
			if errors.Is(copyErr, io.ErrUnexpectedEOF) {
				return fmt.Errorf("条目 %q 只有部分正文: %w", hdr.Name, copyErr)
			}
			return fmt.Errorf("读取条目 %q 失败: %w", hdr.Name, copyErr)
		}
		if closeErr != nil {
			return fmt.Errorf("关闭条目 %q 的输出失败: %w", hdr.Name, closeErr)
		}
	}
}

示例用临时文件突出错误位置，生产代码还应把临时文件改名、设置权限，并在失败时清理未完成文件。关键判断是 errors.Is，而不是比较错误字符串；这样上游包装错误后，截断语义仍然可以被识别。

区分条目截断和头部截断

同一个 io.ErrUnexpectedEOF 可能来自两个阶段。若已经成功拿到 hdr，并且错误发生在 io.Copy，通常说明当前条目的声明大小没有被输入满足；此时 hdr.Name 和 hdr.Size 就是最有价值的上下文。

如果错误发生在 Next，则可能是下一个 512 字节头部、PAX 扩展记录或当前条目末尾的填充不完整。此时不应把它当作“没有更多文件”：io.EOF 和 io.ErrUnexpectedEOF 的业务含义相反，前者可以结束，后者必须失败。

把策略放进流式解包循环

如果目标是把每个条目写入磁盘，直接让 io.Copy 消费 tr 通常比先 io.ReadAll 更适合大文件。tar.Reader 会按当前头部的逻辑大小限制可读内容；复制中遇到上游 EOF 时，它会把“还没满足声明长度”的情况表现为 io.ErrUnexpectedEOF。

流式循环可以按下面的决策顺序组织：

1. 调用 Next，先处理 io.EOF 和其他头部错误。
2. 保存 Header.Name、Header.Size 与当前输出目标的关系。
3. 用 io.Copy 消费正文，任何复制错误都让当前条目失败。
4. 只有正文复制成功，才把临时文件提升为最终文件。

不要在复制返回错误后继续调用 Next 试图“跳过坏文件”。Reader 已经处于输入不可信的状态，继续读取容易把一个截断归档误包装成多个看似独立的错误。

补上大小和资源边界

截断判断和资源限制是两件事。Header.Size 是归档声明的逻辑大小，不能直接当作可信的内存分配值。若业务确实要把条目读入内存，应先设置上限；超出上限时返回业务错误，低于上限但数据不够时仍保留 io.ErrUnexpectedEOF。

func readSmallEntry(tr *tar.Reader, hdr *tar.Header, max int64) ([]byte, error) {
	if hdr.Size  max {
		// 先限制声明大小，避免把不可信的 Header.Size 变成大内存分配。
		return nil, fmt.Errorf("条目 %q 大小 %d 超过上限 %d", hdr.Name, hdr.Size, max)
	}

	data, err := io.ReadAll(io.LimitReader(tr, hdr.Size))
	if err != nil {
		return nil, fmt.Errorf("读取条目 %q 失败: %w", hdr.Name, err)
	}
	if int64(len(data)) != hdr.Size {
		// 限制器读完但长度不足，说明输入没有兑现头部声明。
		return nil, fmt.Errorf("条目 %q 数据不完整: %w", hdr.Name, io.ErrUnexpectedEOF)
	}
	return data, nil
}

这里的长度检查是对业务边界的补充；对于大文件落盘，优先使用流式复制并检查复制错误。不要为了“容错”把短数据补零，因为那会让下游无法区分原始文件和损坏文件。

常见问题

为什么当前文件读完时会返回 io.EOF？

这是当前条目正文的结束信号。处理完它后还要调用 Next，只有 Next 返回的 io.EOF 才表示整个归档没有下一个条目。

可以只判断 err == io.EOF 吗？

不够。至少要分别处理 io.ErrUnexpectedEOF 和其他错误；推荐使用 errors.Is，避免上层包装错误后丢失判断。

发现截断后还能继续解包其他文件吗？

不建议。当前归档的结构或条目数据已经不完整，应保留失败上下文、清理未完成输出，并让调用方重新获得完整输入。

小结

处理 archive/tar 截断输入时，记住三个动作：把 Next 的 io.EOF 视为正常归档结束；把正文复制或下一次推进中的 io.ErrUnexpectedEOF 视为输入不完整；把 Header.Name 和 Header.Size 绑定进错误信息。这样既能支持文件、网络和管道等流式来源，也不会把半个文件误交给后续业务。