文件下载返回404主因是public/storage软链接缺失、失效或路径错误，需检查并重建链接；若使用子目录（如docs/），须在config/filesystems.php中配置links并重运storage:link；同时确认Web服务器DocumentRoot指向public目录。
文件下载返回 404，通常不是代码写错了，而是 public 目录下的符号链接没生效，或者根本没指向正确的物理路径。Laravel 的 Storage::url() 和 asset() 都依赖这个链接结构，一旦断开或错位，图片、PDF、ZIP 等所有通过 public/ 路径访问的资源都会打不开。
确认 public/storage 软链接是否存在且有效
进入你的 Laravel 项目根目录，执行：
ls -la public/storage
你应该看到类似这样的输出：
storage -> ../storage/app/public
如果显示 No such file or directory，说明软链接缺失；如果指向的是错误路径（比如 ../storage/app 少了 /public），或权限被拒绝（Permission denied），也会导致 404。
修复方式很简单：
- 先删除旧链接（如有）：
rm public/storage - 重新生成标准链接：
php artisan storage:link
该命令默认只创建 public/storage → storage/app/public 这一条链接，适用于直接放在 storage/app/public/ 根下的文件（如 storage/app/public/logo.png 对应 URL /storage/logo.png）。
如果你把文件存在子目录（如 images/、docs/），需要额外配 links
例如你把 PDF 存在 storage/app/public/docs/report.pdf，希望用 /docs/report.pdf 直接访问——这不能靠默认链接实现，必须手动配置。
打开 config/filesystems.php，找到 'links' 数组（通常在文件末尾附近），添加你想要的映射：
'links' => [ public_path('storage') => storage_path('app/public'), public_path('docs') => storage_path('app/public/docs'), public_path('images') => storage_path('app/public/images'),],
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
保存后再次运行：php artisan storage:link
此时会按配置创建多个链接：public/docs 指向 storage/app/public/docs，public/images 同理。之后访问 /docs/report.pdf 就能正常下载了。
检查 Web 服务器是否以 public 为根目录
哪怕链接全对，如果 Apache/Nginx 把整个项目根目录（比如 /var/www/myapp）设为 DocumentRoot，而不是 /var/www/myapp/public，那么浏览器请求 /storage/logo.png 实际是在找 /var/www/myapp/storage/logo.png ——显然不存在，必然 404。
验证方法：访问 http://your-domain/robots.txt。如果能看到内容，说明服务器已正确指向 public/；如果报 404 或跳转到首页，大概率根目录配错了。
快速自查（开发环境推荐）：
- 改用内置服务器：
php artisan serve，它默认且强制以public/为根，无需任何配置 - Apache 用户：检查
DocumentRoot是否为"/path/to/your/project/public"，且对应<directory></directory>块中启用了AllowOverride All - Nginx 用户：确认
root指令指向/path/to/your/project/public，不是项目根目录
下载时 URL 生成要匹配实际链接路径
别混用函数。如果你配置了 public/docs → storage/app/public/docs，就该用：
<a href="%7B%7B%20asset('docs/report.pdf')%20%7D%7D">下载</a>
而不是：
<a href="%7B%7B%20Storage::url('docs/report.pdf')%20%7D%7D">下载</a>（这会生成 /storage/docs/report.pdf，但默认链接不支持子目录）
简单记：用 asset() 对应你手动配的 public/xxx 路径；用 Storage::url() 只适用于 public/storage/xxx 下的文件（即走默认链接）。
