PHP业务文件批量打包下载,怎样避免不同目录下的同名文件在ZIP中被覆盖?

发布人:A5数据发布时间:2026-11-16 13:25阅读量:16

ZIP 中的文件名不是由服务器上的完整路径自动决定,而是由写入压缩包时指定的条目路径决定。若把 orders/invoice.pdf 和 refunds/invoice.pdf 都用 basename() 转成 invoice.pdf 再添加,压缩包里就会出现同名条目;不同解压工具对重复条目的处理可能不同,不应依赖某一种覆盖行为。

最直接的办法是保留业务目录结构,让它们分别以 orders/invoice.pdf 和 refunds/invoice.pdf 的路径写入 ZIP。如果业务要求把所有文件平铺在压缩包根目录,则需要给同名文件分配不同名称,例如 invoice.pdf、invoice (2).pdf。

ZIP 中的路径由第二个参数决定

ZipArchive::addFile() 的第一个参数是服务器上的源文件路径,第二个参数是 ZIP 中的条目名称:

$zip->addFile($sourcePath, $entryName);

例如:

$zip->addFile(
    '/srv/app/storage/orders/invoice.pdf',
    'orders/invoice.pdf'
);

$zip->addFile(
    '/srv/app/storage/refunds/invoice.pdf',
    'refunds/invoice.pdf'
);

两个文件虽然都叫 invoice.pdf,但压缩包中的完整条目路径不同,因此可以同时保留。反过来,如果第二个参数都传 invoice.pdf,ZIP 内部就会发生路径冲突。

ZIP 中的路径由第二个参数决定配图

不要把服务器绝对路径直接作为条目名称。这样既可能把服务器目录结构暴露给下载者,也容易生成包含盘符、反斜杠或不合适路径片段的条目。应当明确生成相对于业务目录的 ZIP 路径,并使用 / 作为目录分隔符。

保留目录结构的实现

下面的函数接收业务根目录和一组相对于该目录的文件路径。它会检查文件是否存在、是否可读、是否仍位于指定根目录内,并拒绝重复的 ZIP 条目名称。

<?php

function zipNameKey(string $name): string
{
    // ZIP 条目本身区分大小写,但一些解压环境的文件系统不区分。
    // 用不区分大小写的键进行保守检查,降低跨平台解压时重名的风险。
    if (function_exists('mb_strtolower')) {
        return mb_strtolower($name, 'UTF-8');
    }

    return strtolower($name);
}

/**
 * 将业务文件打包为临时 ZIP,返回临时 ZIP 的路径。
 *
 * $relativeFiles 示例:
 * [
 *     'orders/invoice.pdf',
 *     'refunds/invoice.pdf',
 * ]
 */
function buildBusinessZip(string $rootDir, array $relativeFiles): string
{
    $root = realpath($rootDir);

    if ($root === false || !is_dir($root)) {
        throw new RuntimeException('业务文件根目录不存在或不是目录');
    }

    if ($relativeFiles === []) {
        throw new InvalidArgumentException('没有可打包的文件');
    }

    $tmp = tempnam(sys_get_temp_dir(), 'business-zip-');

    if ($tmp === false) {
        throw new RuntimeException('无法创建临时文件');
    }

    $zip = new ZipArchive();
    $opened = $zip->open($tmp, ZipArchive::OVERWRITE);

    if ($opened !== true) {
        @unlink($tmp);
        throw new RuntimeException('无法创建 ZIP 文件');
    }

    $rootPrefix = rtrim(str_replace('\\', '/', $root), '/') . '/';
    $seen = [];

    try {
        foreach ($relativeFiles as $relativePath) {
            if (!is_string($relativePath) || $relativePath === '') {
                throw new InvalidArgumentException('文件路径必须是非空字符串');
            }

            // 统一分隔符,再拒绝绝对路径、空路径段和目录穿越片段。
            $relativePath = str_replace('\\', '/', $relativePath);

            if (
                $relativePath[0] === '/'
                || preg_match('/^[A-Za-z]:/', $relativePath)
                || strpos($relativePath, "\0") !== false
            ) {
                throw new InvalidArgumentException('只允许传入相对文件路径');
            }

            $parts = explode('/', $relativePath);

            foreach ($parts as $part) {
                if ($part === '' || $part === '.' || $part === '..') {
                    throw new InvalidArgumentException('文件路径包含不允许的片段');
                }
            }

            $candidatePath = $root
                . DIRECTORY_SEPARATOR
                . implode(DIRECTORY_SEPARATOR, $parts);

            $sourcePath = realpath($candidatePath);

            if (
                $sourcePath === false
                || !is_file($sourcePath)
                || !is_readable($sourcePath)
            ) {
                throw new RuntimeException('文件不存在、不是普通文件或不可读');
            }

            // realpath 会解析符号链接;再次确认文件没有通过链接跑到根目录之外。
            $sourceNormalized = str_replace('\\', '/', $sourcePath);

            if (DIRECTORY_SEPARATOR === '\\') {
                $insideRoot = strncasecmp(
                    $sourceNormalized,
                    $rootPrefix,
                    strlen($rootPrefix)
                ) === 0;
            } else {
                $insideRoot = strncmp(
                    $sourceNormalized,
                    $rootPrefix,
                    strlen($rootPrefix)
                ) === 0;
            }

            if (!$insideRoot) {
                throw new RuntimeException('文件不在允许打包的目录范围内');
            }

            // 保留相对目录结构,避免仅同名但位于不同目录的文件相撞。
            $entryName = implode('/', $parts);
            $key = zipNameKey($entryName);

            if (isset($seen[$key])) {
                throw new RuntimeException('ZIP 中存在重复的条目路径');
            }

            if (!$zip->addFile($sourcePath, $entryName)) {
                throw new RuntimeException('添加文件到 ZIP 失败');
            }

            $seen[$key] = true;
        }

        if (!$zip->close()) {
            throw new RuntimeException('写入 ZIP 文件失败');
        }

        return $tmp;
    } catch (Throwable $e) {
        $zip->close();
        @unlink($tmp);
        throw $e;
    }
}

调用时传入相对路径,而不是只传文件名:

$rootDir = '/srv/app/storage/business';

$relativeFiles = [
    'orders/2025/invoice.pdf',
    'refunds/2025/invoice.pdf',
];

$zipPath = buildBusinessZip($rootDir, $relativeFiles);

生成的压缩包中会包含:

orders/2025/invoice.pdf
refunds/2025/invoice.pdf

这里的目录路径可以来自数据库中的业务分类,也可以来自文件在业务根目录下的实际相对位置。关键是不能在构造 entryName 时把它们都简化成 basename($sourcePath)。

用于下载时的处理

buildBusinessZip() 返回临时文件路径。控制器可以在创建成功后发送下载响应,并在发送后清理临时文件:

$zipPath = buildBusinessZip(
    '/srv/app/storage/business',
    [
        'orders/2025/invoice.pdf',
        'refunds/2025/invoice.pdf',
    ]
);

header('Content-Type: application/zip');
header('Content-Disposition: attachment; filename="business-files.zip"');
header('Content-Length: ' . filesize($zipPath));

readfile($zipPath);
unlink($zipPath);
exit;

发送响应前不要输出调试信息、空白字符或页面模板,否则可能导致下载响应头失效。实际项目中还应先确认当前用户有权下载列表中的每一个文件;不要仅凭请求参数拼接磁盘路径后直接打包。

临时文件创建在系统临时目录中,打包完成后才调用 readfile()。不要在 ZipArchive::close() 之前移动或删除源文件,因为压缩包可能尚未完成写入。若请求可能中途终止,应为临时文件设置定期清理机制。

业务要求平铺文件时,自动生成不重复名称

有些下载页面要求 ZIP 打开后直接看到文件,不希望保留多层目录。这时需要把源文件路径与 ZIP 条目名称分开处理:源文件仍从原目录读取,条目名称则由一个分配函数生成。

function uniqueFlatEntryName(string $fileName, array &$used): string
{
    $fileName = basename(str_replace('\\', '/', $fileName));

    $dot = strrpos($fileName, '.');

    // .env 这类以点开头的名称按无扩展名处理。
    if ($dot !== false && $dot > 0) {
        $stem = substr($fileName, 0, $dot);
        $extension = substr($fileName, $dot);
    } else {
        $stem = $fileName;
        $extension = '';
    }

    $candidate = $fileName;
    $number = 2;

    while (isset($used[zipNameKey($candidate)])) {
        $candidate = $stem . ' (' . $number . ')' . $extension;
        $number++;
    }

    $used[zipNameKey($candidate)] = true;

    return $candidate;
}

在打包循环中使用该函数:

$usedNames = [];

foreach ($relativeFiles as $relativePath) {
    // 实际项目中仍应像前面的示例一样验证路径并解析出 $sourcePath。
    $sourcePath = $rootDir . '/' . $relativePath;

    $entryName = uniqueFlatEntryName($relativePath, $usedNames);

    if (!$zip->addFile($sourcePath, $entryName)) {
        throw new RuntimeException('添加文件到 ZIP 失败');
    }
}

假设输入路径为:

orders/invoice.pdf
refunds/invoice.pdf
returns/invoice.pdf

平铺后的条目可以是:

invoice.pdf
invoice (2).pdf
invoice (3).pdf

生成名称时要检查整个候选名称,而不能只统计原始文件名。例如输入列表中本来就有 invoice (2).pdf 时,分配函数需要继续尝试下一个未使用名称。上面的循环会通过 used 集合完成这项检查。

zipNameKey() 对名称做了不区分大小写的检查,这是为了减少在大小写不敏感文件系统上解压时出现冲突的可能。若业务需要严格保留大小写差异,应明确目标解压环境;对中文等 Unicode 文件名有跨平台兼容要求时,还应统一文件名的 Unicode 规范化形式,并在目标环境中验证大小写处理规则。

目录结构、前缀和序号应如何选择

写入 ZIP 的方式示例条目路径适用情况需要注意
保留相对目录orders/invoice.pdf文件原本属于不同业务目录,下载者需要看出来源传入的目录结构应稳定,不能包含服务器绝对路径
增加业务前缀order-1001-invoice.pdf目录不重要,但订单号、分类名等能帮助识别文件前缀应来自可信的业务数据,并限制长度和特殊字符
同名自动加序号invoice.pdf、invoice (2).pdf必须把所有文件放在 ZIP 根目录名称可读性较弱,需处理输入中已有的同名序号

一般来说,业务文件本身已经按类别或日期分目录保存时,保留相对目录最简单,也能保留文件来源信息。只有界面或下游系统确实要求平铺时,才需要额外重命名。

面向承载 PHP 业务与文件下载服务的部署需求,A5idc数据提供香港、美国、日本等地的物理服务器,涵盖 Xeon、AMD EPYC、SSD/NVMe及大容量硬盘配置。香港存储系列提供四块14TB企业级机械硬盘及H730控制器等方案,日本CTG也有多块HDD或SSD配置,可为业务文件存储、压缩包生成与归档提供相应的计算和存储资源选择。

打包前后的核对

写入前可以检查三个条件:

  1. 每个源文件都属于允许打包的业务目录,且当前请求用户有权访问。
  2. 每个 ZIP 条目都使用相对路径,路径分隔符统一为 /,不包含 .. 或服务器绝对路径。
  3. 所有条目名称唯一;如果 ZIP 要在不同操作系统上解压,还要考虑大小写和 Unicode 文件名的兼容性。

打包后可以查看压缩包中的条目清单:

unzip -l /path/to/business-files.zip

确认目录保留模式时,清单里应能看到类似 orders/2025/invoice.pdf 和 refunds/2025/invoice.pdf 的不同路径。若使用平铺模式,则应看到已经分配好的不同文件名。还可以在 PHP 中用 ZipArchive::open() 打开生成文件,再通过 getNameIndex() 遍历条目名称,检查数量和路径是否符合预期。

另外,示例使用 ZipArchive::OVERWRITE 打开的是新建的临时文件,而不是固定业务 ZIP 路径,因此不会有意覆盖已有下载包。若改为直接写入固定文件名,需先明确是否允许替换旧文件,并避免多个并发请求写入同一个 ZIP。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9802.html

相关推荐