Storage::download 返回 404 是因仅支持 local/public 磁盘，S3 等远程磁盘需先下载到本地再调用；中文文件名需用 streamDownload 手动设 Content-Disposition；大文件应避免 download() 内存加载，改用流式响应。
Storage::download 为什么返回 404 或 “File not found”
调用 Storage::download() 报错或返回 404，通常不是方法本身的问题，而是底层文件路径未被正确解析。Laravel 的 Storage::download() 默认只支持 local 和 public 磁盘（且必须是真实存在的本地路径），不支持直接下载 s3 或其他远程磁盘上的文件——它会尝试用 readfile() 读取本地文件系统路径，而 S3 文件没有对应物理路径。
常见错误现象：
- 使用 Storage::disk('s3')->download('xxx.pdf') → 报 File not found at path "xxx.pdf"
- 文件存在但路径写成相对路径（如 ./storage/app/file.pdf）→ 实际应使用磁盘内逻辑路径（如 file.pdf）
- 确认磁盘配置：检查
config/filesystems.php中对应磁盘的'root'是否指向可读的真实目录 - 验证文件是否存在：用
Storage::disk('local')->exists('path/to/file.pdf')先判断 - 避免硬编码绝对路径：不要传
/var/www/storage/app/xxx.pdf，应传磁盘内的相对路径（如exports/report.pdf）
如何用 Storage::download 设置自定义文件名和响应头
Storage::download() 第二个参数就是客户端保存时的文件名，第三个参数是可选的响应头数组。注意：**响应头必须包含 Content-Type，否则浏览器可能无法正确识别类型或触发下载**。
典型使用场景：导出报表、生成 PDF 下载、动态命名附件
return Storage::disk('local')->download(
'exports/invoice_20240515.pdf',
'发票_20240515.pdf',
[
'Content-Type' => 'application/pdf',
'Cache-Control' => 'no-cache',
'X-Content-Type-Options' => 'nosniff',
]
);- 文件名建议用 ASCII 字符；含中文时，部分旧版 IE 需额外加
Content-Disposition处理（见下一条） - 如果要强制浏览器下载而非预览，确保
Content-Type不是浏览器可直接渲染的类型（如text/plain、image/png） - 不要在 headers 中重复设置
Content-Length—— Laravel 会自动计算并覆盖
中文文件名下载失败？Content-Disposition 要手动处理
Chrome/Firefox 支持 UTF-8 编码的 filename*= 格式，但 IE 和部分旧浏览器只认 filename 的 ASCII 值。直接传中文名给 Storage::download() 第二个参数，在 IE 下可能变成乱码或默认为 download.bin。
解决方式：绕过 Storage::download() 的自动头生成，改用 Response::streamDownload() 手动控制 Content-Disposition：
use Illuminate\Support\Facades\Response; use Illuminate\Support\Facades\Storage;return Response::streamDownload(function () { echo Storage::disk('local')->get('exports/订单汇总.xlsx'); }, '订单汇总.xlsx', [ 'Content-Type' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'Content-Disposition' => 'attachment; filename="dingdan.xlsx"; filename*=UTF-8\'\'%E8%AE%A2%E5%8D%95%E6%B1%87%E6%80%BB.xlsx', ]);
-
filename是 fallback（ASCII 名），filename*是 RFC 5987 格式的 UTF-8 编码名，用rawurlencode()处理中文 - 不要省略
attachment;前缀，否则可能被当成 inline 内容 - 流式下载适合大文件，避免内存溢出；小文件用
Storage::download()更简洁
大文件下载卡顿或超时？别用 download() 直接读内存
Storage::download() 底层调用 readfile()，会把整个文件一次性加载进 PHP 内存再输出。对于几百 MB 的日志或备份文件，极易触发 memory_limit 超限或 max_execution_time 中断。
正确做法是使用流式响应（stream），让 Web 服务器（如 Nginx）接管文件传输，PHP 只负责发起响应头：
use Illuminate\Support\Facades\Storage; use Illuminate\Http\Response;$filePath = 'backups/large_dump.sql.gz'; $fullPath = Storage::disk('local')->path($filePath);
if (! file_exists($fullPath)) { abort(404); }
return response()->streamDownload(function () use ($fullPath) { $fp = fopen($fullPath, 'rb'); while (! feof($fp)) { echo fread($fp, 8192); obflush(); flush(); } fclose($fp); }, 'backup' . date('Ymd_His') . '.sql.gz', [ 'Content-Type' => 'application/gzip', 'Content-Length' => filesize($fullPath), ]);
- 务必校验
$fullPath是否真实存在且可读，Storage::disk()->path()只对local磁盘有效 - 使用
fread($fp, 8192)分块读取，避免内存暴涨 - Nginx 用户建议启用
X-Accel-Redirect（需配置）替代 PHP 流式，性能更高
实际项目中，最容易被忽略的是磁盘类型与下载能力的匹配关系：S3 文件必须先临时下载到本地磁盘，再用 Storage::disk('local')->download()；而流式方案里，filesize() 和 fopen() 对非 local 磁盘完全不可用——这些边界情况，比语法本身更常导致线上故障。
