Go archive/tar.Reader.Next 如何安全跳过目录项：流式读取与错误边界

解 tar 包时，最容易漏掉的不是文件内容，而是目录项和不安全路径。archive/tar.Reader.Next 每次前进都会返回一个 *tar.Header，当前条目没读完的内容会被自动丢弃；因此，跳过目录只需要判断 Header.Type，不要额外把目录内容读进内存。

稳妥的处理顺序是：先判断 Next 的错误，再用 Header.Name 做本地路径校验，最后只对普通文件调用 io.Copy；遇到 io.EOF 是正常结束，遇到 ErrInsecurePath 则应停止写盘。

先把 Reader.Next 的边界看清楚

tar 是顺序格式，Reader 同时扮演“条目迭代器”和“当前文件读取器”。调用 Next 后，返回的 Header.Size 决定接下来能从 Reader 读出多少字节。如果上一个条目只读了一半，下一次 Next 仍会先把剩余内容和对齐填充丢掉，然后再返回下一个条目。

这条规则很适合做筛选：目录、符号链接或不需要的文件都可以直接 continue。不要为了“清空”而再读一遍，因为那会把跳过逻辑和实际写盘逻辑搅在一起。

最小配方：跳过目录，只写普通文件

下面的示例把目标目录固定为 out，并保留 Header.Name 的相对层级。实际项目还应根据业务决定是否允许符号链接；这里直接拒绝非普通文件，减少解包器的行为面。

package main

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

func unpack(r io.Reader, out string) error {
	tr := tar.NewReader(r)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return err
		}
		if hdr.Typeflag == tar.TypeDir {
			continue
		}
		if hdr.Typeflag != tar.TypeReg {
			continue
		}
		if !filepath.IsLocal(hdr.Name) {
			return fmt.Errorf("不安全路径: %s", hdr.Name)
		}
		dst := filepath.Join(out, hdr.Name)
		if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
			return err
		}
		f, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
		if err != nil {
			return err
		}
		_, copyErr := io.Copy(f, tr)
		closeErr := f.Close()
		if copyErr != nil {
			return copyErr
		}
		if closeErr != nil {
			return closeErr
		}
	}
}

这里的检查点有三个：到达末尾时返回 nil；目录项不创建本地目录；普通文件的内容直接来自当前的 Reader。io.Copy 返回后，当前条目的字节已经消费完，下一轮 Next 可以继续前进。

路径安全不能只靠 Join

filepath.Join(out, hdr.Name) 只负责拼接路径，不等于授权。一个带有绝对路径、.. 路径段或平台不接受的本地路径，可能让输出位置偏离预期。Go 的 archive/tar 文档把这类名称称为 non-local name；当 GODEBUG=tarinsecurepath=0 时，Next 还可能同时返回 Header 和 ErrInsecurePath。

因此，错误分支不能只写成“err 不为空就退出”然后忽略 Header，也不能为了继续解包而无条件忽略安全错误。对不可信 tar 包，看到 ErrInsecurePath 就停止；对完全由自己生成的内部归档，也要在调用方明确记录为何接受这个边界。

参数和错误边界的速查

• Header.Typeflag：目录用 tar.TypeDir，普通文件用 tar.TypeReg；未处理的类型不应默认写盘。
• Header.Name：它来自归档元数据，写入本地前必须做本地路径判断。
• io.EOF：只代表整个归档读取结束，不是当前文件损坏。
• ErrInsecurePath：说明路径不满足本地路径规则；对不可信输入应拒绝。

还有一个容易忽视的资源问题：每次打开目标文件后都要在当前循环内关闭，不能把 defer f.Close() 放在长循环里等待函数返回，否则大量条目会同时占用文件描述符。

常见问题

目录项需要调用 os.MkdirAll 吗？

如果只关心普通文件，可以跳过目录项，并在写文件前用 os.MkdirAll(filepath.Dir(dst), ...) 创建父目录。这样既能处理归档中的隐式目录，也不会重复创建。

遇到 io.EOF 时能继续调用 Next 吗？

不能把它当成可恢复错误。io.EOF 表示归档已经结束，当前函数应正常返回；继续调用没有业务意义。

ErrInsecurePath 可以忽略吗？

技术上可以由调用方选择接受返回的 Header，但对外部上传或下载得到的 tar 包不建议忽略。拒绝并记录归档名称，通常比把文件写到意外目录更安全。

把解包流程收紧到三个判断

实际落地时，可以把流程固定为“Next 取条目、Typeflag 过滤类型、IsLocal 验证路径”。普通文件通过后才创建父目录并复制内容；任何非 io.EOF 的读取错误都保留原始错误返回。这个顺序足够短，也能把目录跳过、流式读取和路径安全放在同一条可复查的控制流里。