LaravelAPI如何实现文件下载_Laravel文件下载接口步骤【指南】-Laravel-PHP中文网

Laravel 文件下载失效主因是路径错误、响应头缺失或 Web 服务器配置不当；须用绝对路径、response()->download($path, $filename) 设文件名、大文件改用 streamDownload() 或 Nginx/X-Accel-Redirect 直接处理。

laravelapi如何实现文件下载_laravel文件下载接口步骤【指南】

下载接口返回 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 超时。

Laravel Cloud

Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

改用 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 提示。