ZipArchive 手动打包最稳：检查文件存在可读、addFile用相对名、中文转GBK、close前ob_end_clean、php://output直输流、Storage用path()取真实路径、禁用Nginx缓冲。
用 ZipArchive 手动打包多个文件最稳
PHP 原生 ZipArchive 是 Laravel 多文件压缩下载最可控的方式，不依赖第三方包，兼容 PHP 7.4+ 和常见服务器环境。Laravel 自带的 response()->download() 只能返回单个文件，必须自己生成 ZIP 流或临时 ZIP 文件再响应。
常见错误是直接把路径数组丢给 ZipArchive::addFile() 却忽略文件是否存在、路径是否可读、中文名乱码——这些都会导致 ZIP 损坏或下载后解压失败。
- 先检查每个文件是否存在且可读：
file_exists($path) && is_readable($path) - 添加文件时用
addFile($realPath, $archiveName)，第二个参数控制压缩包内显示的文件名，避免绝对路径泄露（比如不要传/var/www/storage/app/file.pdf，而传invoice.pdf） - 中文文件名需转为 GBK 编码（Windows 解压器默认认这个），
iconv('UTF-8', 'GBK', $filename)；macOS/Linux 用户解压正常，但别指望 Windows 用户点开就看到正确名字 - 打包完记得
close()，否则 ZIP 文件头不完整，浏览器下载后提示“文件已损坏”
Laravel 控制器里怎么安全返回 ZIP 流
不能直接 return response()->download($zipPath) 然后删临时文件——并发请求下可能删错，或还没响应完就被删了。应该用内存流方式，避免磁盘 IO 和清理风险。
典型场景：用户勾选 5 个 PDF 报表，点击「批量下载」，后端生成 ZIP 并立即返回，不落地存储。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 实例化
ZipArchive后调用open('php://output')，直接写入响应体 - 设置响应头：
Content-Type: application/zip，Content-Disposition: attachment; filename="files.zip" - 关键：在
ob_end_clean()后再输出，防止 Laravel 中间件或日志提前写入空白字符，导致 ZIP 头损坏 - 示例片段：
ob_end_clean(); header('Content-Type: application/zip'); header('Content-Disposition: attachment; filename="batch.zip"'); $zip = new ZipArchive(); $zip->open('php://output', ZipArchive::CREATE); foreach ($paths as $path) { if (file_exists($path)) { $zip->addFile($path, basename($path)); } } $zip->close();
用 Storage::disk('local')->getDriver() 读取文件时要注意什么
如果文件存在 storage/app/ 下，想用 Laravel 的 Storage 门面读取再塞进 ZIP，别直接传 Storage::get($path) 返回的内容给 addFromString() ——大文件会吃光内存，且丢失原始 MIME 类型和时间戳。
更稳妥的做法是拿到真实路径再交给 ZipArchive，而不是走内存中转。
-
Storage::disk('local')->path($relativePath)返回绝对路径（如/var/www/storage/app/reports/a.pdf），可直接用于addFile() - 别用
Storage::url()，那是给前端访问用的 HTTP 地址，不是文件系统路径 - 如果用了自定义 disk（比如
s3），path()不可用，必须先pull()到临时目录再压缩，否则无法直接 addFile - 注意权限：确保 web server 用户（如
www-data）对源文件有读取权限，否则addFile()静默失败
Chrome 下载中断、Safari 提示“无法打开”通常是哪几个点没处理好
不是代码逻辑错，而是 HTTP 响应细节没对齐浏览器预期。尤其在 Nginx + PHP-FPM 环境下，容易因缓冲、超时、头信息顺序出问题。
- 关掉 Laravel 的全局输出缓冲（
ob_end_clean()必须在ZipArchive::close()前执行） - Nginx 配置里确认没有
fastcgi_buffering off;或proxy_buffering off;被误启用，否则 ZIP 流被截断 - 避免在 ZIP 生成过程中触发任何日志写入（比如
Log::info()），它可能往响应体里混入 JSON 或空格 - Safari 对
Content-Length更敏感，别手动设这个 header，让 PHP 自己算；如果用了php://output，就别碰Content-Length
复杂点在于：ZIP 本身不校验完整性，出错时浏览器只报“损坏”，你得从头查路径、编码、缓冲、权限四个层面。最容易被忽略的是 ob_end_clean() 的位置和 Nginx 的 fastcgi 缓冲行为。
