Go archive/tar.Reader.Next 怎么安全遍历归档条目

我第一次用 archive/tar 读取归档时，最容易把 Next 想成“取下一行”。它实际推进的是一个完整的 tar 条目：成功后拿到 *tar.Header，当前条目的正文则继续通过同一个 Reader 读取。安全遍历的关键是固定这个节奏：先处理上一个条目的剩余数据，再调用 Next；把 io.EOF 视为正常结束，把其他错误当作损坏或不可接受的输入。

一、用 Next 驱动顺序遍历并区分结束信号

一个稳定的循环只需要三种结果：拿到 Header、读到 io.EOF、遇到其他错误。Header.Size 描述当前文件正文的逻辑字节数；当本条目还有未读数据时，下一次 Next 会自动跳过它，所以不需要手动 Seek，也不能把 tar 流当作随机访问文件。

tr := tar.NewReader(src)
for {
	// Next 会推进到下一个条目；未读完的当前正文会被自动丢弃。
	hdr, err := tr.Next()
	if err == io.EOF {
		break // 正常到达归档尾部，不把 EOF 当作失败。
	}
	if err != nil {
		return fmt.Errorf("读取 tar 头部失败: %w", err) // 损坏输入立即停止。
	}
	// hdr 代表当前条目，正文仍从 tr 读取。
	if err := handleEntry(tr, hdr); err != nil {
		return err
	}
}

这里的 src 可以是文件、网络响应或其他 io.Reader。如果业务需要记录进度，记录条目名和已处理字节即可，不要尝试从 Reader 反推随机偏移。

二、根据 Header.Typeflag 处理文件、目录和链接

遍历不是“见到名称就创建文件”。TypeReg 才是普通文件；TypeDir 表示目录，TypeSymlink 与 TypeLink 表示两类链接。特殊类型的正文通常没有可复制的数据，直接对它们做 io.Copy 既没有意义，也会掩盖业务分支。

目录和链接的判断应发生在读取正文之前。尤其是链接，归档中的 Linkname 可能指向输出根目录之外；如果只把 Name 拼到目标目录就创建，最终写入位置可能偏离预期。

三、读取文件内容并约束名称、大小与输出位置

真正落盘时，我会把三个边界放在同一段代码里：名称必须是本地路径，正文不能超过允许上限，目标路径必须位于受控目录内。Go 文档中 Next 还说明了非本地名称与 ErrInsecurePath 的关系，但是否接受这类名称仍应由提取程序明确决定。

func handleEntry(tr *tar.Reader, hdr *tar.Header) error {
	// 先拒绝非本地名称，避免把绝对路径或上级路径直接写入目标目录。
	if !filepath.IsLocal(hdr.Name) {
		return fmt.Errorf("拒绝非本地路径: %q", hdr.Name)
	}

	switch hdr.Typeflag {
	case tar.TypeDir:
		return os.MkdirAll(filepath.Join("out", hdr.Name), 0o755) // 目录不读取正文。
	case tar.TypeSymlink, tar.TypeLink:
		return fmt.Errorf("默认拒绝链接条目: %q -> %q", hdr.Name, hdr.Linkname) // 链接目标需单独策略。
	case tar.TypeReg, tar.TypeRegA, 0:
		if hdr.Size  64

示例选择拒绝链接，是因为“能否恢复链接”属于业务决策，不应由遍历函数偷偷替读者决定。生产代码还应让 out 使用绝对根目录，并在创建前把清理后的路径与根目录比较；若要支持跨平台归档，需额外考虑路径分隔符、大小写和符号链接竞态。

四、用检查清单收束常见误区

• 不要把 io.EOF 记录成失败；只有它表示正常遍历结束。
• 不要在处理完 Header 后忘记读取或主动跳过正文；虽然下一次 Next 会清理剩余数据，但业务统计可能因此丢失。
• 不要只信任 Header.Name；链接的 Linkname、文件大小和条目类型同样影响提取安全。
• 不要把 Header.Size 当成内存分配指令；流式读取配合上限更适合大归档。

相关问题

Next 返回 ErrInsecurePath 时要不要继续？

默认应停止并记录条目名；只有业务明确允许非本地名称时，才在完成额外路径策略后使用返回的 Header。

目录条目需要调用 Read 吗？

不需要。目录没有可复制的正文，按 TypeDir 创建目录即可。

为什么不能只用 io.Copy 读取所有条目？

因为链接、目录和特殊类型的处理目标不同，而且不设大小上限会让异常归档消耗过多资源。