必须绕过默认缓冲、确保路径真实可读、手动控制响应头与输出流；小文件用Storage::download()，大文件必须用response()->streamDownload()流式处理，并显式设置X-Accel-Buffering: no等关键头。
要在 Laravel 中安全、稳定地提供文件下载服务，必须绕过默认缓冲机制、确保路径真实可读、手动控制响应头与输出流，否则大文件会内存溢出、小文件可能被 Nginx 缓存截断、浏览器无法识别类型导致直接打开而非下载。
用 Storage::download() 快速下载小文件
适合 PDF、PNG、TXT 等小于 5MB 的文件，调用简单但不适用于大文件或需要精细控制响应头的场景。
第一步：确认文件存在且路径相对于 storage/app 目录，例如 public/documents/invoice.pdf。
第二步：在控制器中写 return Storage::download('public/documents/invoice.pdf', '发票_202608.pdf');
第三步：注意 【第二个参数是用户看到的文件名，必须显式传入，否则浏览器会用原始路径名，含 public/ 前缀】；若省略，下载名可能是 invoice.pdf，但更常见的是 public_documents_invoice_pdf（取决于 Web 服务器 URL 解码行为）。
这一步操作起来很简单，直接把文件路径和自定义名填进去就行。但别忘了检查 Storage::exists()，否则 404 错误会暴露 storage 目录结构。
用 response()->streamDownload() 实现流式下载
这是处理 Excel、视频、日志压缩包等大文件的唯一可靠方式，避免内存爆满，同时支持动态生成内容。
方法一：基础流式下载（带路径校验与缓冲关闭）
先用 storage_path() 构造绝对路径，不能用 public_path() 或相对路径——【file_exists() 必须返回 true，否则 fopen 失败，且 Web 进程需对文件有 r 权限】。
return response()->streamDownload(function () use ($absolutePath) { $fp = fopen($absolutePath, 'rb'); fpassthru($fp); fclose($fp); }, 'report_2026.zip')->header('X-Accel-Buffering', 'no');
方法二：手动分块读取 + flush（更可控，兼容性更强）
用 ob_end_clean() 清掉可能存在的输出缓冲，防止 headers already sent 错误；每次 fread() 后立即 echo + flush()，但必须配合 Nginx fastcgi_buffering off 配置，否则 flush 无效。
return response()->stream(function () use ($absolutePath) { ob_end_clean(); $fp = fopen($absolutePath, 'rb'); if (!$fp) { abort(404); } while (!feof($fp)) { echo fread($fp, 8192); flush(); } fclose($fp); }, 200)->header('Content-Type', 'application/zip')->header('Content-Transfer-Encoding', 'binary')->header('X-Accel-Buffering', 'no');
为下载响应添加自定义 Header
所有响应头都必须通过 Response 实例链式设置，绝不能在控制器里用原生 header() 函数——那会导致 headers already sent 错误，且在中间件之后完全失效。
在 download 或 streamDownload 返回前，追加 withHeaders() 或多个 header()：
return Storage::download($path, $name)->withHeaders([ 'X-Download-ID' => Str::uuid(), 'Cache-Control' => 'no-cache, no-store, must-revalidate', 'Content-Disposition' => 'attachment; filename="' . $name . '"', 'Content-Type' => 'application/octet-stream' ])
注意：Content-Type 必须明确指定，否则浏览器可能根据文件扩展名猜测类型，某些情况下会触发内联显示而非下载；【Content-Disposition 的 filename 值必须用双引号包裹，含空格或中文时尤其关键】。
如果需要全局统一加审计头（如 X-Trace-ID），应新建中间件，在 handle() 中对 $response 设置 $response->headers->set('X-Trace-ID', ...)，注册到 web 或 api 组。
