Java Commons Compress怎样逐条读取tar归档项

处理 tar 归档时，真正需要循环的不是“文件路径列表”，而是 TarArchiveEntry 元数据与当前项的字节流。Java Commons Compress 提供的 TarArchiveInputStream 会把 tar 暴露为一个可以逐项读取的输入流：调用 getNextEntry() 定位下一项，再用普通 read() 消费当前项。

官方地址：https://commons.apache.org/proper/commons-compress/

我在接入归档导入时遇到过一个容易忽略的情况：目录项、文件项和异常文件名都混在同一条流里。如果只写一个“读到结尾”的循环，能看到文件名，却不一定能安全、完整地处理每一项。下面从读取链开始，把它收敛成可放进服务端的写法。

先看清 getNextEntry() 和当前字节流

TarArchiveInputStream 继承自归档输入流。每次调用 getNextEntry()，返回一个新的 TarArchiveEntry；在下一次调用前，read() 只对应当前归档项。返回 null，表示没有下一项了。

这也解释了为什么不能把 TarArchiveInputStream 当作一个普通文件流后只调用一次 read()：一次读取只覆盖当前项，不会自动替你遍历后续项。

建立可关闭并明确编码的读取链

读取本地 tar 时，外层文件流负责文件资源，缓冲流减少小块读取开销，最内层的 tar 流负责解析归档记录。项目文档支持在构造器中显式传入文件名编码；如果归档由不同平台生成，编码策略要和生产数据约定一致，不要把乱码问题留到业务层猜测。

org.apache.commonscommons-compress1.28.0

下面的代码只负责“逐条读取并记录元数据”，不把整个归档加载进内存：

import java.io.BufferedInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import org.apache.commons.compress.archivers.tar.TarArchiveEntry;
import org.apache.commons.compress.archivers.tar.TarArchiveInputStream;

public final class TarEntries {
    private TarEntries() {
        // 工具类不需要实例化。
    }

    public static void list(Path tarPath) throws IOException {
        // try-with-resources 确保底层文件句柄和归档流一起关闭。
        try (InputStream fileIn = Files.newInputStream(tarPath);
             BufferedInputStream bufferedIn = new BufferedInputStream(fileIn);
             TarArchiveInputStream tarIn = new TarArchiveInputStream(bufferedIn, "UTF-8")) {
            TarArchiveEntry entry;
            while ((entry = tarIn.getNextEntry()) != null) {
                // 每次循环只处理当前 entry 的元数据和字节流。
                System.out.printf("name=%s, directory=%s, size=%d%n",
                        entry.getName(), entry.isDirectory(), entry.getSize());

                // 目录没有文件内容；文件项的字节要被消费完再进入下一项。
                if (!entry.isDirectory()) {
                    byte[] buffer = new byte[8192];
                    while (tarIn.read(buffer) != -1) {
                        // 示例只统计/消费字节，实际业务可在这里写入目标流。
                    }
                }
            }
        }
    }
}

这里的关键不是缓冲区必须是 8192 字节，而是生命周期和循环边界清晰：一个归档流只对应一次外层资源关闭，当前项消费完以后再请求下一项。

读取文件项时，先做能力和路径边界处理

如果目标是解包，而不是只列清单，就要把“归档中的名字”当作不可信输入。目录需要先创建，文件名需要规范化，并且规范化后的路径必须仍位于目标目录内。Commons Compress 还提供了 canReadEntryData()，遇到当前实现无法读取的归档特性时，可以让业务选择记录并跳过，而不是盲目写文件。

import java.io.BufferedInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import org.apache.commons.compress.archivers.ArchiveEntry;
import org.apache.commons.compress.archivers.tar.TarArchiveEntry;
import org.apache.commons.compress.archivers.tar.TarArchiveInputStream;

public final class SafeTarExtractor {
    private SafeTarExtractor() {
        // 工具类不需要实例化。
    }

    public static void extract(Path tarPath, Path outputDir) throws IOException {
        Path root = outputDir.toAbsolutePath().normalize();
        Files.createDirectories(root);

        // 所有流都由同一组资源边界管理，避免异常路径留下打开的文件。
        try (InputStream fileIn = Files.newInputStream(tarPath);
             BufferedInputStream bufferedIn = new BufferedInputStream(fileIn);
             TarArchiveInputStream tarIn = new TarArchiveInputStream(bufferedIn, "UTF-8")) {
            ArchiveEntry rawEntry;
            byte[] buffer = new byte[8192];
            while ((rawEntry = tarIn.getNextEntry()) != null) {
                if (!tarIn.canReadEntryData(rawEntry)) {
                    // 当前实现不支持该项时记录并跳过，不能把它当成普通文件写出。
                    continue;
                }

                TarArchiveEntry entry = (TarArchiveEntry) rawEntry;
                Path target = root.resolve(entry.getName()).normalize();
                if (!target.startsWith(root)) {
                    // 防止 ../ 或绝对路径把内容写到目标目录之外。
                    throw new IOException("归档项越过目标目录: " + entry.getName());
                }

                if (entry.isDirectory()) {
                    Files.createDirectories(target);
                    continue;
                }

                Path parent = target.getParent();
                if (parent != null) {
                    Files.createDirectories(parent);
                }
                try (OutputStream out = Files.newOutputStream(target)) {
                    int count;
                    while ((count = tarIn.read(buffer)) != -1) {
                        // 流式写出当前项，不把大文件整体读入内存。
                        out.write(buffer, 0, count);
                    }
                }
            }
        }
    }
}

这段代码的安全检查只解决路径越界和资源管理，不代表所有归档安全问题都自动消失。生产服务还应限制单项大小、总解包大小、文件数量以及允许的后缀，并对失败项保留可检索的归档名。

发布前排查这几个容易踩坑的点

• 不要继续使用已弃用方法。 新代码使用 getNextEntry()，不要把 getNextTarEntry() 当成首选入口。
• 不要把大小当成唯一依据。 getSize() 用于元数据展示很方便，但实际复制仍应以 read() 返回值为准。
• 不要吞掉当前项。 如果业务只关心某些后缀，也要明确决定是否消费或跳过当前项，再进入下一次 getNextEntry()。
• 不要默认文件名编码永远正确。 UTF-8 只是示例，归档来源和历史格式决定了应使用的编码策略。
• 不要用归档名直接拼接路径。 先规范化，再做 startsWith(root) 目录边界判断。

可以把发布前检查压缩成一句话：能否逐项定位，当前项是否完整消费，流是否必然关闭，名字是否不会越界，异常是否留下足够上下文。满足这五点，逐条读取 tar 才从“能跑”变成可维护的归档处理。

相关问题

TarArchiveInputStream 能直接读取 tar.gz 吗？

不能把 gzip 压缩层当作 tar 层直接解析。tar.gz 需要先用 Commons Compress 的 gzip 解压输入流，再把解压后的流交给 TarArchiveInputStream；本文只聚焦纯 tar 的逐项读取。

为什么读取归档项时不能一次性 read 到整个文件？

单个归档项可能很大，一次性读入会放大堆内存压力。以固定缓冲区循环读取当前项，才能让内存占用与文件大小解耦。

读取 tar 时怎样处理中文文件名？

构造 TarArchiveInputStream 时显式传入与归档来源约定一致的编码，并把该约定写入接口或任务配置，避免每次遇到乱码才临时修改。