根本原因是传入的路径不是服务器上真实可读的绝对路径；必须用storage_path()或public_path()生成绝对路径，禁用相对路径或URL，确保file_exists()返回true且Web进程有读权限。
response()->download() 为什么返回 404 或空白页
根本原因就一个：传进去的路径不是服务器上真实可读的绝对路径。Laravel 不会帮你解析相对路径或 URL，它只认 file_exists() 能返回 true 的路径。
- ✅ 正确写法：
response()->download(storage_path('app/reports/2024.pdf'))或response()->download(public_path('uploads/file.zip')) - ❌ 错误写法：
response()->download('/storage/report.pdf')（Web 路径，非文件系统路径） - ❌ 错误写法：
response()->download('storage/app/report.pdf')（相对路径，PHP 找不到） - 路径必须存在且 Web 进程有读权限；
storage:link只影响 public 访问，不影响storage_path()的使用 - API 路由默认不走 session 中间件，但下载本身不依赖它——真正卡住的是路径校验失败后抛出的
FileNotFoundException，被异常处理器转成 500 或静默吞掉
中文文件名在 Chrome/Safari 里乱码或截断
不是 Laravel 没处理，而是它默认用原始 ASCII 编码 filename 字段，而现代浏览器要求 RFC 5987 格式的 filename*= 声明。
- 别手动拼
header('Content-Disposition', ...)，会和 Laravel 内置逻辑冲突 - 正确做法是显式传入第二参数，并补一个标准头：
response()->download($path, $name)->header('Content-Disposition', 'attachment; filename*=UTF-8\'\'' . rawurlencode($name)) - 如果要兼容旧 IE，得同时提供 ASCII 备用名：
attachment; filename="report.pdf"; filename*=UTF-8\'\'%E5%B9%B4%E5%BA%A6%E6%8A%A5%E5%91%8A.pdf - 避免空格、括号、斜杠等特殊字符；用
Str::slug($name, '_') . '.pdf'预处理更稳妥
大文件下载卡死、超时或内存爆掉
response()->download() 会把整个文件读进 PHP 内存再输出，100MB 就可能触发 Allowed memory size exhausted。这不是配置调高就能解决的问题，而是设计使然。
- 改用
response()->streamDownload()，配合fopen($path, 'rb')流式读取：response()->streamDownload(function () use ($path) { $fp = fopen($path, 'rb'); fpassthru($fp); fclose($fp); }, $filename); - Nginx 默认开启
fastcgi_buffering on，会缓存整条响应；必须加->header('X-Accel-Buffering', 'no')关闭缓冲 - PHP 的
max_execution_time和memory_limit对流式响应意义不大，但需确保output_buffering = Off或设为0 - 对 GB 级日志或导出包，更稳方案是让 Nginx 直接服务文件（
X-Accel-Redirect），完全绕过 PHP
Storage::download() 报 “File not found” 却明明存在
这个方法只对 local 和 public 磁盘有效，且它内部用的是磁盘的 getAdapter()->getPathPrefix() 拼路径——不是你想象中的 “当前目录”，而是配置里 'root' => storage_path('app') 这种定义。
- 调用
Storage::disk('s3')->download('x.pdf')必报错，因为 S3 没有本地路径；它会尝试读取/var/www/storage/app/x.pdf，而不是拉取远程对象 - 验证方式：
Storage::disk('local')->exists('exports/data.csv')返回true，才代表该磁盘内路径存在 - 不要传绝对路径给
Storage::download()，只传磁盘内的相对路径（如'invoices/2024/05.pdf'） - 如果文件在
storage/app/private/下，且磁盘配置了'root' => storage_path('app')，那路径就是'private/report.pdf'
realpath() + str_starts_with() 校验，可能直接暴露 /etc/passwd。 
