Go archive/tar 怎样逐项读取归档并限制输出路径

用 Go 读取 tar 归档时，核心不是先把整个文件解压到内存，而是把输入流交给 tar.NewReader，循环调用 Next 获取一个 Header，再读取当前条目的内容。真正需要额外小心的是输出路径：归档成员名来自外部输入，不能直接和输出目录拼接后写盘。

官方资料：https://pkg.go.dev/archive/tar#Reader

本文只讨论标准库 archive/tar 的逐项读取、Header 信息和输出路径限制。示例中的图片都是静态说明图，不是运行截图或执行证据。

先理解 Next 和 Header 的职责

tar.NewReader 接受一个 io.Reader，返回按顺序访问归档内容的读取器。每次调用 Next，读取器都会前进到下一个条目，并返回一个 *tar.Header。Header.Name 是归档中的成员名，Header.Typeflag 表示目录、普通文件或链接等类型，Header.Size 是当前文件的逻辑字节数。

当归档结束时，Next 返回 io.EOF。如果上一个条目的数据还没有读完，下一次 Next 会自动丢弃当前条目的剩余数据，所以循环不需要手工 Seek 到下一个偏移。

package main

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

func printEntries(tarPath string) error {
	// 输入文件只负责提供连续字节，tar.Reader 负责识别每个条目的边界。
	f, err := os.Open(tarPath)
	if err != nil {
		return fmt.Errorf("打开 tar 文件失败: %w", err)
	}
	defer f.Close()

	tr := tar.NewReader(f)
	for {
		hdr, err := tr.Next()
		if errors.Is(err, io.EOF) {
			// 没有下一个 Header，说明归档已经正常结束。
			return nil
		}
		if err != nil {
			return fmt.Errorf("读取 tar Header 失败: %w", err)
		}

		fmt.Printf("name=%q type=%d size=%d\n", hdr.Name, hdr.Typeflag, hdr.Size)
		// 当前循环体内的 tr.Read 只会读取这个 Header 对应的文件数据。
	}
}

按条目类型读取或跳过内容

读取条目时不要只看 Header.Name。目录应该创建目录后继续，普通文件才需要打开目标文件并复制内容；符号链接、硬链接、设备文件和 FIFO 则应根据应用需求明确拒绝或单独处理。对于一个只接收普通文件的导入器，跳过未知类型通常比把它们当作文件写入更容易控制。

复制普通文件时，Header.Size 是一个有用的边界。io.CopyN(dst, tr, hdr.Size) 会要求恰好复制指定字节数；如果归档在中途结束，函数会返回错误，调用方就不会把一个截断文件当成成功结果。

// copyRegularEntry 只把当前普通文件条目的内容写入已经打开的目标文件。
func copyRegularEntry(dst *os.File, tr *tar.Reader, size int64) error {
	if size 

这里的目标文件必须在调用前已经创建并且位于经过检查的目标路径下。关闭目标文件也要处理错误，尤其是输出位于网络文件系统或磁盘空间紧张的环境时，关闭阶段可能才暴露写入问题。

在 Join 之前限制输出路径

安全顺序是“检查成员名，再清理，再拼接”，而不是先调用 filepath.Join 再凭字符串猜测结果。filepath.IsLocal 可以先拒绝绝对路径和会离开当前目录的路径；通过后再用 filepath.Clean 得到稳定的相对名称，最后才与固定输出根目录调用 filepath.Join。

典型的危险输入包括 ../outside.txt、/absolute/path.txt 以及 Windows 下的盘符或 UNC 路径。归档的成员名通常使用斜杠，所以若应用还要跨平台处理名称，可以先按目标平台的路径语义统一处理，再执行同一套拒绝策略。

func safeDestination(root, memberName string) (string, error) {
	// 先检查原始成员名，避免把绝对路径或目录穿越名带入输出目录。
	if !filepath.IsLocal(memberName) {
		return "", fmt.Errorf("拒绝非本地归档路径: %q", memberName)
	}

	cleanName := filepath.Clean(memberName)
	if cleanName == "." || cleanName == ".." {
		return "", fmt.Errorf("拒绝空目录或父目录条目: %q", memberName)
	}
	// Join 会清理结果，但安全性来自前面的 IsLocal，而不是 Join 本身。
	return filepath.Join(root, cleanName), nil
}

上面的函数需要导入 path/filepath。如果目标平台的路径规则、归档格式或业务约束更严格，可以在 IsLocal 后增加允许的扩展名、最大路径长度或文件大小限制。

组合成可复用的安全解包函数

下面的实现把几个关键点放在同一个循环中：固定输出根目录、先检查成员名、目录使用 MkdirAll、普通文件按大小复制、非普通文件明确跳过。示例选择跳过链接，而不是跟随链接写入目标文件；这样不会把链接目标误认为普通文件内容。

package unpack

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

func ExtractTar(tarPath, outputRoot string) error {
	// 输出根目录由调用方指定，归档中的 Name 不能改变它。
	if err := os.MkdirAll(outputRoot, 0o755); err != nil {
		return fmt.Errorf("创建输出目录失败: %w", err)
	}

	src, err := os.Open(tarPath)
	if err != nil {
		return fmt.Errorf("打开归档失败: %w", err)
	}
	defer src.Close()

	tr := tar.NewReader(src)
	for {
		hdr, err := tr.Next()
		if errors.Is(err, io.EOF) {
			return nil
		}
		if err != nil {
			return fmt.Errorf("读取归档条目失败: %w", err)
		}

		dstPath, err := safeDestination(outputRoot, hdr.Name)
		if err != nil {
			return err
		}

		switch hdr.Typeflag {
		case tar.TypeDir:
			// 目录条目只创建目录，不从 Reader 复制数据。
			if err := os.MkdirAll(dstPath, 0o755); err != nil {
				return fmt.Errorf("创建目录 %q 失败: %w", hdr.Name, err)
			}
		case tar.TypeReg, tar.TypeRegA:
			if err := os.MkdirAll(filepath.Dir(dstPath), 0o755); err != nil {
				return fmt.Errorf("创建父目录失败: %w", err)
			}
			// 写入前使用条目权限的低位，避免把归档元数据直接当作完整权限策略。
			mode := os.FileMode(hdr.Mode) & 0o777
			out, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, mode)
			if err != nil {
				return fmt.Errorf("创建文件 %q 失败: %w", hdr.Name, err)
			}
			_, copyErr := io.CopyN(out, tr, hdr.Size)
			closeErr := out.Close()
			if copyErr != nil {
				return fmt.Errorf("写入文件 %q 失败: %w", hdr.Name, copyErr)
			}
			if closeErr != nil {
				return fmt.Errorf("关闭文件 %q 失败: %w", hdr.Name, closeErr)
			}
		default:
			// 链接和特殊文件不在本例中落盘；需要支持时必须单独设计策略。
		}
	}
}

这段代码还需要把 safeDestination 放在同一个包中。生产代码通常还会加入总解包字节数、单文件大小、条目数量和磁盘配额限制，防止合法路径下的超大归档耗尽资源。

容易忽略的边界

第一，成员名安全不等于链接目标安全。官方文档对 tar.Reader.Next 的路径检查针对的是文件名，链接目标需要应用自己决定是否允许、是否改写为普通文件，或直接拒绝。本文示例选择跳过链接，因此没有尝试解析 Header.Linkname。

第二，Clean 不是权限和资源策略。filepath.Clean 只做词法清理；它不会检查目标是否已经存在，也不会阻止重复文件名覆盖旧文件。若业务不允许覆盖，应在打开文件时改用存在性检查或更严格的创建策略。

第三，权限位不能原样信任。Header.Mode 可能来自不可信归档。示例只取常见权限低位，并把目录权限固定为 0755；实际系统应根据运行用户、租户和部署环境再收紧。

第四，版本行为要留意。当前 archive/tar 文档说明，在特定 GODEBUG 设置下，Next 可能返回带有 ErrInsecurePath 的 Header；程序不能把这个错误静默当作普通成功。无论是否启用该行为，应用自己的路径策略仍应保留。

小结

相关问题

为什么不能只判断 strings.HasPrefix(dstPath, root)？

字符串前缀可能把相邻目录误判为同一根目录，而且不同平台的分隔符、盘符和清理规则不同。先对成员名做平台相关的本地路径判断，再拼接固定根目录更清晰。

目录条目也要调用 Read 吗？

不需要。目录、链接和特殊条目的 Read 没有普通文件内容；处理这类条目时应按类型执行明确的创建、跳过或拒绝策略。

io.Copy 会不会读到下一个 tar 条目？

tar.Reader 会在当前条目结束时返回 io.EOF，不会把下一个条目内容作为当前文件返回。使用 io.CopyN 仍然有助于把预期大小与实际读取结果对齐，并及时暴露截断输入。