Go archive/tar.Reader.Next 如何安全遍历归档：未读数据、EOF 与路径校验边界

用 Go 读取 tar 包时，真正容易出错的地方不是把文件读出来，而是没有把 Reader.Next 当成“切换当前条目”的边界：当前条目没读完，下一次调用会自动丢弃剩余数据；读到归档末尾则要识别 io.EOF，而写盘前还应检查条目路径是否安全。

稳妥的遍历顺序是：tar.NewReader 创建读取器，循环调用 Reader.Next，用 Header.Size 约束当前内容，遇到 io.EOF 正常收尾，并在 Header.Name 进入文件系统前通过 filepath.IsLocal 做路径校验。

先看清 Reader.Next 切换了什么

tar.NewReader 返回的是顺序读取器。第一次调用 Reader.Next 取得第一个 Header，之后的 Read 只针对这个条目的内容。Header.Size 决定当前条目最多能读多少字节；当前条目读到末尾时，Read 返回 io.EOF，但这只是“这一项结束”，不是整个归档结束。

我更建议把归档末尾判断集中在 Reader.Next 的错误分支里。这样不会把某个小文件的 EOF 误判成整个输入已经结束。

一个可复用的顺序遍历骨架

下面的示例只把归档内容读入内存，目的是展示边界处理。实际写文件时，还要把路径校验放在落盘动作之前。

package main

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

func listTar(r io.Reader) error {
    tr := tar.NewReader(r)
    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }

        data, err := io.ReadAll(tr)
        if err != nil {
            return fmt.Errorf("read %s: %w", hdr.Name, err)
        }
        fmt.Printf("%s %d bytes\n", hdr.Name, len(data))
    }
}

这里的关键关系是：Reader.Next 成功后，ReadAll(tr) 只消费当前条目；下一轮再次调用 Reader.Next 才进入下一个条目；最终的 io.EOF 才表示归档没有更多 header。

不需要的条目可以让 Next 自动跳过

如果业务只关心某一种后缀，不必先把所有内容读完再筛选。拿到 Header.Name 后直接 continue，下一次 Reader.Next 会自动丢弃当前条目尚未读取的内容和填充字节，然后定位到下一项。

这条规则很适合做归档目录扫描，但不要把它理解成“可以随意忽略错误”。Next 返回非空错误时，应该先判断是否为 io.EOF；其他错误要停止处理，避免把损坏归档当成完整目录。

写入磁盘前处理非本地路径

归档里的 Header.Name 不是天然安全的目标路径。Go 当前的 archive/tar 文档说明，在 GODEBUG=tarinsecurepath=0 时，遇到非本地名称的 Reader.Next 会返回带 ErrInsecurePath 的 header；“拿到 header”不等于可以直接拼接目标目录。

如果程序要把内容写到磁盘，应先用 filepath.IsLocal 判断名称，再把经过校验的名称交给 os.OpenFile。对于不接受的条目，记录原因并跳过或终止，取决于业务是否要求归档完整可信。

func safeTarget(root, name string) (string, error) {
    if !filepath.IsLocal(name) {
        return "", tar.ErrInsecurePath
    }
    return filepath.Join(root, name), nil
}

这段代码展示的是判断顺序，不是完整的权限模型：真正落盘时还要考虑符号链接、目标目录权限和覆盖策略。至少不要在路径校验之前调用 os.OpenFile。

几个容易混淆的边界

把当前文件的 EOF 当成归档结束

Read 返回 io.EOF 后，仍然可以调用 Reader.Next 读取下一个 header。只有 Reader.Next 返回 io.EOF，才是整个归档的正常结束。

跳过条目后手动再读一次

如果只看 header 就直接进入下一轮，Next 会处理剩余字节。额外调用一次 io.Copy(io.Discard, tr) 通常没有必要，还可能让代码把“跳过策略”分散到多个位置。

收到 ErrInsecurePath 就照常写盘

ErrInsecurePath 是路径安全信号，不是可以忽略的普通提示。除非业务明确接受非本地名称，并且后续有独立的安全约束，否则应该拒绝该条目。

最后用三条检查收口

遍历代码可以按这三点复核：一是 Reader.Next 的 io.EOF 是否单独处理；二是条目内容是否始终通过当前的 reader 消费，避免混用外层输入流；三是 Header.Name 是否在 os.OpenFile 之前经过 filepath.IsLocal 和目标策略校验。

把这三个边界守住后，tar 遍历就不会因为短文件、跳过条目或异常路径产生隐蔽偏差。

相关问题

Reader.Next 返回 io.EOF 时需要再调用一次吗？

不需要。它表示归档已经没有下一个 header，循环可以正常结束。

Header.Size 需要自己截断 Read 的长度吗？

正常使用 tar.Reader 时，Reader 已经按当前条目的 Header.Size 管理读取边界；业务仍应检查 ReadAll 或 Copy 的错误。

所有 tar 文件都必须拒绝非本地路径吗？

如果内容要落盘，默认拒绝更稳妥。确实需要保留这类名称时，也应先定义隔离目录、符号链接和覆盖策略，而不是直接拼接路径。