Laravel 文件下载失效主因是路径错误、响应头缺失或 Web 服务器配置不当；须用绝对路径、response()->download($path, $filename) 设文件名、大文件改用 streamDownload() 或 Nginx/X-Accel-Redirect 直接处理。
下载接口返回 404 或空白页，response()->download() 不生效
常见于路由没配对或文件路径错误。Laravel 的 response()->download() 要求文件物理路径必须存在且 Web 服务器有读取权限，不能是相对路径或 URL。
- 确保传入
response()->download()的是绝对路径，比如storage_path('app/public/report.pdf')，不是'/storage/report.pdf' - 如果文件在
public/下，用public_path('uploads/file.zip')；若在storage/app/，先确认是否已配置软链接或使用Storage::disk('local')->path() - API 路由默认不走 Web 中间件（如
EncryptCookies），但下载本身不依赖它；真正影响的是响应头——别在控制器里手动return response()->stream()却忘了exit，否则可能被后续中间件截断
Laravel API 下载时前端收不到文件名，浏览器默认叫 “download”
这是因为 API 响应默认没设 Content-Disposition 头，或者用了 response()->file() 这类只适合展示、不带下载语义的方法。
- 必须用
response()->download($path, $filename)，第二个参数才是真实文件名，比如'invoice-2024.pdf' - 避免在文件名里用中文或空格，最好用
Str::slug($name) . '.pdf'处理，否则某些浏览器（尤其是 Safari）会乱码或截断 - 不要自己拼
header('Content-Disposition: attachment; filename=...')，Laravel 已封装好逻辑，手动加反而可能重复或冲突
大文件下载卡住、超时或内存爆掉
response()->download() 默认把整个文件读进内存再吐出去，100MB 以上的文件很容易触发 PHP 内存限制或 Nginx 超时。
- 改用
response()->streamDownload()，配合fopen($path, 'rb')流式读取，示例：response()->streamDownload(function () use ($path) { $fp = fopen($path, 'rb'); while (!feof($fp)) { echo fread($fp, 8192); } fclose($fp); }, $filename); - Nginx 需要关闭缓冲：
fastcgi_buffering off;，否则它会等完整响应才转发给浏览器 - PHP 的
max_execution_time和memory_limit要调高，但更推荐让 Web 服务器直接处理静态文件下载（见下一条）
想绕过 Laravel 直接让 Nginx / Apache 发送文件（最稳方案）
对公开可下载的文件（如用户上传后生成的报告），让 Web 服务器接管比 PHP 处理更高效、更可靠。
- 把文件放到
public/downloads/下，用response()->redirectTo('/downloads/report.pdf')重定向，Nginx 自动处理 Range 请求和断点续传 - 如果必须隐藏真实路径，用 Nginx 的
X-Accel-Redirect（或 Apache 的X-Sendfile），在控制器里设置响应头：return response()->make('', 200, [ 'X-Accel-Redirect' => '/protected-files/app/reports/2024/invoice.pdf', ]);对应 Nginx 配置location /protected-files/ { internal; alias /var/www/laravel/storage/app/; } - 这个方案不经过 PHP 内存，也不受
php.ini限制，但需要运维配合配置，本地开发时容易漏掉
文件下载看着简单，实际卡点全在路径、响应头、Web 服务器配合这三层。最容易被忽略的是：你以为在下文件，其实浏览器收到的是 200 OK 的 HTML 页面——先检查 Network 面板里的响应内容类型和状态码，再查日志里的 file not found 提示。
