PHP业务文件批量打包下载,怎样避免不同目录下的同名文件在ZIP中被覆盖?
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 条目名称。
<?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配置,可为业务文件存储、压缩包生成与归档提供相应的计算和存储资源选择。
打包前后的核对
写入前可以检查三个条件:
- 每个源文件都属于允许打包的业务目录,且当前请求用户有权访问。
- 每个 ZIP 条目都使用相对路径,路径分隔符统一为
/,不包含..或服务器绝对路径。 - 所有条目名称唯一;如果 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

