当前位置：首页 > 文章列表 > Golang > Go教程 > Go archive/tar.Reader.Next 如何安全跳过目录项：流式读取与错误边界

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

来源：17golang原创 2026-08-28 02:26:48 0浏览收藏

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

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

要点速览

Reader.Next 会自动丢弃上一个条目的剩余数据和填充字节。
目录项用 Header.Type == tar.TypeDir 跳过，普通文件才进入写盘分支。
filepath.IsLocal 负责拒绝绝对路径与路径逃逸，不能只检查字符串前缀。
io.EOF 表示 tar 读取完毕，ErrInsecurePath 表示路径安全边界未通过。

先把 Reader.Next 的边界看清楚

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

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

Reader.Next 读取 tar 条目后跳过目录并进入普通文件写盘分支的二维工程逻辑插画 — Reader.Next 将条目交给 Header.Type 判断，目录项跳过后，普通文件才进入写盘。

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

下面的示例把目标目录固定为 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 就停止；对完全由自己生成的内部归档，也要在调用方明确记录为何接受这个边界。