必须运行php artisan storage:link创建public/storage软链接，否则Storage::url()生成的/storage/xxx路径因Web服务器无法访问storage/app/public而404；该链接将public/storage指向storage/app/public，使文件可通过HTTP直接访问。
用 public 磁盘上传文件，路径不是“随便写哪都行”，而是严格绑定在 storage/app/public/ 下，且必须通过 php artisan storage:link 暴露到 Web 可访问路径。跳过这步，Storage::url() 生成的 /storage/xxx 链接一定 404。
为什么 Storage::url() 返回的链接打不开
因为 public 磁盘的物理路径是 storage/app/public/，但 Web 服务器默认不直接访问这个目录。Laravel 用软链接把 public/storage 指向它，所以 URL 路径前缀是 /storage/，而非 /public/ 或其他。
-
Storage::disk('public')->put('a.jpg', $content)→ 实际写入storage/app/public/a.jpg -
Storage::disk('public')->url('a.jpg')→ 返回/storage/a.jpg - Nginx/Apache 必须能从
public/storage/a.jpg读到文件，靠的是public/storage这个软链接存在 - 如果手动删了软链接、或部署时没运行
php artisan storage:link，就必然 404
store() 和 storeAs() 写在哪？路径怎么算
两个方法都只接受相对路径（不能带 ../ 或绝对路径），且都基于磁盘的 root 配置拼接。对 public 磁盘，默认 root 是 storage_path('app/public')，所以：
-
$request->file('avatar')->store('avatars', 'public')→ 存为storage/app/public/avatars/xxx.jpg -
$request->file('avatar')->storeAs('avatars/2026', 'user.png', 'public')→ 存为storage/app/public/avatars/2026/user.png - 路径开头不能加斜杠，
storeAs('/avatars/user.png')会变成storage/app/public//avatars/user.png（双斜杠不影响读写，但难看） - 不要用
move()直接写进public/目录——绕过 Storage 抽象，后续无法用url()、download()，也丢失事件和日志
部署后 storage:link 失效或报错怎么办
常见于 Linux 权限不足、SELinux 启用、或容器环境未挂载 public/ 目录。关键不是“重试命令”，而是确认三件事：
- 执行命令的用户（如 www-data）对
public/目录有写权限：ls -ld public/看 owner/group，必要时chown -R www-data:www-data public/ - 软链接目标路径必须存在：
storage/app/public目录得先被 Laravel 自动创建（首次store()或手动mkdir -p storage/app/public） - Docker 或某些 PaaS（如 Laravel Forge）可能禁用符号链接，此时需改用 Nginx
alias或 ApacheAlias映射，而不是依赖软链 - 别在 Windows 开发环境生成软链然后 git 提交——
public/storage应该是 gitignored，部署时再生成
最易被忽略的一点：APP_URL 必须带协议和域名，否则 Storage::url() 生成的链接是相对路径或错误前缀；比如 APP_URL=http://localhost 才能确保返回 http://localhost/storage/xxx，而不是 //storage/xxx 或 /storage/xxx（后者在子目录部署时会出错）。
