Laravel 文件下载核心是 response()->download() 方法返回带正确 HTTP 头的响应。基础下载需确保本地文件存在且可读，推荐用 storage_path() 或 public_path() 构建绝对路径；动态生成下载用 streamDownload() 配合闭包输出内容；安全下载须校验权限并从 private 目录读取后流式响应；注意中文文件名编码、大文件内存限制及 Web 服务器配置。
在 Laravel 中处理文件下载请求，核心是使用 response()->download() 方法返回一个带有正确 HTTP 头的响应，触发浏览器下载行为。
基础下载：本地文件路径
最常见场景是提供项目中已存在的文件（如 storage/app 或 public 目录下的文件）供用户下载。
- 确保文件存在且可读，否则会抛出
Symfony\Component\HttpFoundation\File\Exception\FileNotFoundException - 推荐使用
storage_path()或public_path()构建绝对路径 - 可选传入第二个参数指定下载时的文件名（含扩展名）
return response()->download(storage_path('app/reports/2024-summary.pdf'), '年度报告.pdf');
动态生成后即时下载（如 Excel、PDF）
不保存到磁盘，而是生成内容后直接流式响应。适合导出报表、生成临时凭证等场景。
- 用
response()->streamDownload()接收一个闭包，闭包内输出原始内容（如用fputcsv写 CSV，或用 Dompdf/TCPDF 渲染 PDF） - 需手动设置
Content-Type和Content-Disposition头 - 注意内存和超时限制，大文件建议改用临时存储 + redirect 方式
$data = [['姓名', '邮箱'], ['张三', 'zhang@example.com']];
return response()->streamDownload(function () use ($data) {
$fp = fopen('php://output', 'w');
foreach ($data as $row) {
fputcsv($fp, $row);
}
fclose($fp);
}, 'users.csv', [
'Content-Type' => 'text/csv',
]);
带权限校验的安全下载
不能直接暴露 storage 或 public 路径给前端，应通过路由+控制器做访问控制。
- 把文件存放在
storage/app/private/等非公开目录 - 在控制器中验证用户是否有权下载该文件（如检查所属关系、权限字段）
- 通过
Storage::disk('local')->get($path)读取内容，再用response()->stream()返回
if (! $user->can('view', $document)) {
abort(403);
}
$content = Storage::disk('local')->get("private/documents/{$document->id}.pdf");
return response($content)
->header('Content-Type', 'application/pdf')
->header('Content-Disposition', 'attachment; filename="'.$document->title.'.pdf"');
注意事项与常见问题
避免踩坑的关键点：
- 中文文件名需 URL 编码，Laravel 5.5+ 的
download()会自动处理；旧版本可用rawurlencode()手动编码 - 大文件下载慎用
download()（会一次性加载进内存），优先考虑StreamedResponse或 Nginx/Apache 的 X-Sendfile/X-Accel-Redirect - 确保 web 服务器（如 Nginx）未拦截
/storage路由，否则public/storage符号链接方式可能失效 - API 请求中下载需前端配合设置
responseType: 'blob'，否则响应体可能被 JSON 解析器误处理
基本上就这些。用对方法，下载逻辑既安全又轻量。
