storage:link 命令在 public/ 目录下创建指向 storage/app/public/ 的符号链接，仅用于 http 访问静态资源，不复制文件、不改权限、不触发事件；laravel 运行不依赖它，但 storage::url() 生成的 /storage/xxx 路径需与该链接对齐才能正确访问。
storage:link 命令到底做了什么
它只是在 public/ 目录下创建一个指向 storage/app/public/ 的符号链接（symlink），不复制文件、不修改权限、也不触发任何事件。Laravel 本身完全不依赖这个链接运行，它只服务于你通过 HTTP 直接访问图片这类静态资源的场景。
常见错误现象：404 Not Found 访问 /storage/xxx.jpg；或者页面显示路径正确但图片不加载——大概率是链接根本没建，或建错位置。
- 必须在项目根目录执行，不是
public/下 - 链接目标固定为
storage/app/public，不能改路径（除非重写AppProvidersAppServiceProvider中的Storage::build()配置） - windows 用户用 git bash 或 WSL 执行更可靠；CMD/PowerShell 默认拒绝创建 symlink，除非以管理员身份运行且启用了开发者模式
为什么 public/storage 必须指向 storage/app/public
因为 Storage::disk('public') 的底层配置默认读写 storage/app/public/，而 Laravel 的 URL 生成器（比如 Storage::url()）硬编码返回 /storage/xxx 这个前缀。两者必须对齐，否则路径生成和实际文件存放就脱节了。
使用场景：上传头像、文章封面图等需要公开访问的用户生成内容；不适用于私有文件（如合同 PDF），那些该走 Storage::disk('local') + 控制器响应流式下载。
-
config/filesystems.php里'public'磁盘的'root'必须是storage_path('app/public') - 调用
Storage::putFile('avatars', $request->file('avatar'))时，文件实际落在storage/app/public/avatars/xxx.jpg -
Storage::url('avatars/xxx.jpg')返回/storage/avatars/xxx.jpg—— 这个/storage正是public/storage链接暴露出来的路径
执行失败的三个高频原因
报错 The "public/storage" link already exists. 不代表成功，可能是个坏链接；报错 Could not create symbolic link 多半卡在权限或系统限制。
- 链接已存在但目标路径被手动删过 → 先运行
rm public/storage（linux/macos）或del publicstorage（Windows CMD），再重试 - 本地开发用 Valet / Laravel Sail / docker → 容器内外路径映射不一致，
storage:link要在容器内执行，不是宿主机 - 生产环境用 Forge / Envoyer 部署 → 链接得加到部署脚本里（例如
php artisan storage:link放在deploy.sh的最后），否则每次新版本上线链接就丢失
不用 storage:link 的替代方案
不是所有环境都允许 symlink，比如某些共享主机或 CI 构建流程。这时候就得绕开它，但代价是失去 Laravel 的路径抽象。
性能影响极小，兼容性上：symlink 在绝大多数 Linux/macOS 服务器没问题；Windows iis 需开启“启用符号链接”策略，nginx 则默认支持。
- 直接把
storage/app/public/整个目录复制进public/（不推荐：部署麻烦、容易覆盖、无法热更新） - 在 Nginx/apache 配置里加一条 alias：
location /storage { alias /path/to/your/storage/app/public; }—— 更干净，且无需 PHP 参与 - 用控制器代理图片请求（
return Storage::response($path)）→ 安全但慢，不适合高并发图片场景
真正容易被忽略的是：软链接本身不会自动同步文件变更，如果某天你手动往 storage/app/public/ 里扔了文件，但忘了检查 public/storage 是否还活着，线上就直接 404。定期加个 ls -la public/storage 看一眼，比什么都管用。