PHP ZipArchive在Cpanel无法生成可下载压缩包，本地运行正常

本地正常运行的ZIP打包下载功能，部署到Cpanel后点击下载按钮出现异常，页面输出部分文件名及乱码，无法正常触发文件下载。

原代码 #

$fileEntry = FileEntry::with('childEntriesRecursive')->where('shared_id', $shared_id)->notExpired()->firstOrFail();
abort_if(!static::accessCheck($fileEntry), 404);
$zip_file = str_replace(' ', '_', $fileEntry->name).'.zip';
$zip = new ZipArchive();
$zip->open(public_path($zip_file), ZipArchive::CREATE | ZipArchive::OVERWRITE);
foreach ($fileEntry->childEntriesRecursive as $key => $file) {
    $getFile = storage_path('app/public/'.$file->path);
    if (file_exists($getFile) && is_file($getFile)){
        echo $file->name;
        $zip->addFile(storage_path('app/public/'.$file->path), $file->name);
    }
}
$zip->close();

return response()->download($zip_file, basename($zip_file))->deleteFileAfterSend(true);

问题原因及修复方案 #

• 权限与路径错误：Cpanel环境下public目录通常限制写入权限，将临时ZIP文件放到storage/app/temp目录更稳妥。需提前创建该目录并设置正确权限。
• 输出污染：代码中的echo $file->name;会在下载响应头之前输出内容，破坏HTTP响应结构，导致浏览器无法识别为文件下载，直接删除该行。
• 路径传递不完整：response()->download()需传入完整绝对路径，避免相对路径在Cpanel环境下解析出错。

修改后的代码 #

$fileEntry = FileEntry::with('childEntriesRecursive')->where('shared_id', $shared_id)->notExpired()->firstOrFail();
abort_if(!static::accessCheck($fileEntry), 404);

$zip_file = str_replace(' ', '_', $fileEntry->name) . '.zip';
$temp_dir = storage_path('app/temp');

// 确保临时目录存在并设置权限
if (!file_exists($temp_dir)) {
    mkdir($temp_dir, 0755, true);
}

$zip_path = $temp_dir . '/' . $zip_file;
$zip = new ZipArchive();

// 检查ZIP文件是否能正常打开
if ($zip->open($zip_path, ZipArchive::CREATE | ZipArchive::OVERWRITE) !== true) {
    abort(500, '创建压缩包失败');
}

foreach ($fileEntry->childEntriesRecursive as $file) {
    $file_path = storage_path('app/public/' . $file->path);
    if (file_exists($file_path) && is_file($file_path)) {
        $zip->addFile($file_path, $file->name);
    }
}

$zip->close();

return response()->download($zip_path, basename($zip_path))->deleteFileAfterSend(true);

内容的提问来源于stack exchange，提问作者shazim ali