Java归档解压怎样限制输出路径在目标目录内

Java 使用 Apache Commons Compress 解压归档时，限制输出路径的关键不是给文件名拼一个目标目录，而是把归档项名称当作不可信的元数据：先得到目标根目录的绝对规范化路径，再把归档项名称解析到根目录下，最后确认结果仍然位于根目录内。目录项和文件项分别处理，复制过程使用固定缓冲区，所有流交给 try-with-resources 管理。

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

Apache Commons Compress 官方指南明确提醒，ArchiveEntry.getName() 返回的是归档内部保存的原始名称，不保证是相对路径，也不保证对目标操作系统有效。因此，安全解包的职责要落在业务层的路径构造函数里。

先明确归档项名称不是安全路径

ArchiveInputStream 通过 getNextEntry() 逐项定位归档内容。当前项的 ArchiveEntry.getName() 只是归档元数据，可能包含父目录跳转、绝对路径或当前文件系统不接受的写法。它不能直接作为 Files.newOutputStream() 的目标路径。

需要保留的关系很简单：归档流负责提供项，业务代码负责解释名称，Path.normalize() 负责消解路径表达，目标根目录负责提供允许写入的边界。只有规范化后的目标路径仍以根目录开头，才可以继续写盘。

把目标根目录和归档名称合成安全路径

下面的辅助方法只做一件事：将一个归档项名称映射成目标根目录内的路径。如果名称解析后越过根目录，直接抛出异常，调用方可以记录归档名并终止本次解包。

import java.io.IOException;
import java.nio.file.Path;

public final class ArchivePaths {
    private ArchivePaths() {
        // 路径工具只提供静态方法，不允许实例化。
    }

    public static Path resolveInside(Path outputRoot, String entryName) throws IOException {
        // 根目录先绝对化并规范化，避免相对工作目录影响边界判断。
        Path root = outputRoot.toAbsolutePath().normalize();
        // resolve 后再 normalize，才能把 ../ 等路径表达还原成实际层级。
        Path target = root.resolve(entryName).normalize();
        if (!target.startsWith(root)) {
            // 归档项不能把内容写到目标根目录之外。
            throw new IOException("归档项越过目标目录: " + entryName);
        }
        return target;
    }
}

这里的 startsWith(root) 是路径对象的层级判断，不是字符串前缀判断。不要先把路径转成字符串再比较，因为字符串比较会把目录名相似、分隔符差异等问题混进安全逻辑。

按目录与文件项分别写出

路径边界确认后，解包循环仍然要区分目录和文件。目录项只创建目录；文件项先创建父目录，再从归档输入流按块复制到输出流。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.ArchiveInputStream;
import org.apache.commons.compress.archivers.ArchiveStreamFactory;

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

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

        // 缓冲外层文件流，并保证归档流、输入流在异常时一起关闭。
        try (InputStream fileIn = Files.newInputStream(archive);
             BufferedInputStream bufferedIn = new BufferedInputStream(fileIn);
             ArchiveInputStream in = new ArchiveStreamFactory()
                     .createArchiveInputStream(bufferedIn)) {
            ArchiveEntry entry;
            byte[] buffer = new byte[8192];
            while ((entry = in.getNextEntry()) != null) {
                // 不支持的特性不能按普通文件输出，交给日志和失败策略处理。
                if (!in.canReadEntryData(entry)) {
                    continue;
                }

                Path target = ArchivePaths.resolveInside(root, 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 = in.read(buffer)) != -1) {
                        // 固定缓冲区流式复制，避免把大文件整体放进堆内存。
                        out.write(buffer, 0, count);
                    }
                }
            }
        }
    }
}

示例使用工厂按流识别归档类型；如果业务只允许 ZIP 或 TAR，也可以显式传入对应格式，减少输入范围。无论选择哪种方式，路径边界检查都不能省略。

把解包限制补在路径检查之外

normalize() 只解决路径表达，不能替应用承担所有解包风险。生产服务至少应为单项大小、总输出大小、文件数量和允许的文件类型设置上限，并为每个拒绝项记录归档名、原因和任务标识。

还要注意符号链接和覆盖策略：是否允许覆盖已有文件、是否允许保留归档权限、是否接受链接类型，都应作为业务规则明确下来。路径落在根目录内，只能证明写入位置没有越界，不能替代这些策略。

一份紧凑的发布前速查表

• 名称不可信：不直接使用 entry.getName() 作为输出路径。
• 先做层级判断：resolve().normalize() 后用 Path.startsWith() 对比根目录。
• 区分项类型：目录创建父级，文件才打开 OutputStream。
• 逐项处理：调用 getNextEntry() 前，当前文件项应被完整消费或明确跳过。
• 保留边界：能力、单项大小、总解包量、文件数、覆盖和链接策略都要可配置。

这套做法的核心不是某个单独的 API，而是把“归档名称解释”和“文件写出”拆成两个边界：前者决定能不能落在目标根目录内，后者决定如何以有限资源完成输出。只要这两个边界都由代码明确表达，归档解压就不会停留在简单拼路径的脆弱实现上。

相关问题

为什么不能直接使用 root.resolve(entry.getName())？

resolve() 只是组合路径；归档项带有父目录跳转或绝对路径时，结果可能脱离目标根目录。必须在 normalize() 后做 startsWith(root) 层级判断。

canReadEntryData 返回 false 时应该怎样处理？

根据业务记录并跳过，或将本次任务标记为失败；不要继续把当前项当作普通文件复制。官方指南将它定位为判断当前实现是否能读取该项的能力方法。

路径在根目录内就代表解包安全了吗？

不代表。还要限制单项和总解包大小、文件数量，决定覆盖和链接策略，并确保所有流都能关闭。