Laravel文件系统是抽象层，需正确配置driver及参数：local驱动须设绝对root路径，public驱动需运行storage:link建软链，S3驱动必填key/secret/region/bucket/url；disk名须与config中key完全一致，URL访问依赖软链和Web服务器配置，切换存储后端须手动迁移文件并验证权限与链接。
Laravel 的文件系统（Storage）不是“存东西就完事”，它是一套抽象层，背后可以对接本地磁盘、S3、FTP、甚至内存或缓存。直接硬编码 file_put_contents 或 Storage::disk('local')->put() 而不理解配置逻辑，很容易在换环境时爆错、丢文件、权限失控。
config/filesystems.php 里 disk 配置项怎么填才不踩坑
每个 disk 是一个独立的文件操作入口，它的行为由 driver 和对应驱动的参数共同决定。常见错误是只改了 driver 却漏配底层依赖字段。
-
'local'驱动必须确保'root'指向绝对路径（如/var/www/myapp/storage/app），相对路径在 CLI 和 Web 请求中行为不一致 -
'public'驱动默认用localdriver，但要求'root'指向storage/app/public，且需运行php artisan storage:link建软链到public/storage -
's3'驱动必须显式设置'key'、'secret'、'region'、'bucket'、'url'（用于生成可访问 URL），缺一不可；若用 IAM role（如 EC2），可省略key/secret，但需确认 PHP SDK 权限上下文 - 自定义 disk（如
'backups'）建议复用现有 driver，避免重复写适配器逻辑；不要在 config 里写env('BACKUP_DISK')，而应在.env中设FILESYSTEM_DISK=backups，再通过config('filesystems.default')切换
Storage::disk() 调用时为什么报 “Driver [xxx] not supported”
这个错误不是代码写错，而是配置没加载或拼写不一致。Laravel 启动时只注册 config/filesystems.php 中 'disks' 数组里定义的 key，其余全被忽略。
- 检查
config/filesystems.php是否以return [ ... ]结尾，中间有没有echo、var_dump或未闭合括号 - 确认调用时传入的 disk 名和配置里的 key 完全一致：大小写、下划线、空格都不能差 ——
Storage::disk('S3')和Storage::disk('s3')是两个不同 disk - 如果 disk 依赖
.env变量（如'key' => env('AWS_ACCESS_KEY_ID')），运行php artisan config:clear后再试；缓存配置会固化旧值，不重新读 .env - 第三方包（如
spatie/laravel-backup）可能注册自己的 disk，但不会自动合并进 Laravel 主配置 —— 查看该包文档是否要求手动在config/filesystems.php中添加条目
public disk 的 URL 为什么 404 或返回下载而不是预览
public disk 的设计目标是「可公开访问的静态资源」，但它本身不提供 HTTP 服务，只是个文件操作接口。URL 能否访问，完全取决于 Web 服务器配置和软链状态。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 必须运行
php artisan storage:link，该命令在public/下创建指向storage/app/public/的软链；没这步，Nginx/Apache 根本找不到文件 - Nginx 配置中不能遗漏
location /storage { alias /var/www/myapp/storage/app/public; }这类规则（如果不用软链方式）；更推荐软链，统一走/storage/xxx - 上传时用了
Storage::disk('public')->put('image.jpg', $content)，但生成 URL 时写了Storage::disk('public')->url('image.jpg')—— 这个 URL 是/storage/image.jpg，前提是软链已建且 Web 服务器允许访问/storage路径 - 浏览器强制下载而非预览，大概率是 MIME type 未正确识别，检查 Nginx 的
types块是否包含image/jpeg jpg;等映射，或在Storage::disk('public')->put()时显式传入第三参数['Content-Type' => 'image/jpeg']
如何安全地切换生产环境的存储后端（比如从 local 切到 S3）
切存储后端不是改个配置就能上线，核心风险在于：已有文件不自动迁移、URL 生效延迟、权限策略错配。不能只靠改 .env 和清缓存。
- 先在新 disk（如
s3）上跑通单个文件读写：Storage::disk('s3')->put('test.txt', 'ok')+Storage::disk('s3')->get('test.txt')，确认网络、凭证、bucket 权限都 OK - 用
php artisan tinker手动执行迁移脚本，把publicdisk 下的历史文件同步到 S3（注意保持目录结构和文件名），别依赖自动化工具黑盒操作 - 更新
.env中FILESYSTEM_DISK=s3，同时在config/filesystems.php中确保'default' => env('FILESYSTEM_DISK', 'local')，这样切换才生效 - 关键：S3 的
url()返回的是带签名的临时链接（如果启用了'options' => ['CacheControl' => 'max-age=31536000']）或永久公开 URL（需 bucket policy 允许GetObject），别假设它和 local 的路径格式一样；前端所有asset()或Storage::url()调用必须经过真实环境验证
真正麻烦的从来不是“怎么写一行 Storage 代码”，而是当 Storage::disk('s3')->url() 返回的链接在测试环境能打开、生产环境 403、CI 环境根本连不上时，你得知道该去查 AWS IAM policy、还是 Laravel 的 config/filesystems.php 拼写、还是 Docker 容器里没装 openssl 扩展导致 SDK 签名失败。
