必须安装overtrue/flysystem-oss才能使storage::disk('oss')正常工作，仅装aliyuncs/oss-sdk-php不够；需正确配置endpoint（带https://）、bucket（纯名称）、access_key、secret_key，并运行php artisan config:clear。
直接用 Storage::disk('oss') 前，必须确认 Flysystem 适配器已注册——只装 aliyuncs/oss-sdk-php 是不够的，它只是底层 SDK，不提供 Laravel 的 disk 驱动支持。
为什么 Storage::disk('oss')->put() 报 Disk [oss] does not exist
这是最常见、也最容易卡住人的第一步错误。根本原因不是密钥或 endpoint 写错，而是 Laravel 根本没加载到名为 oss 的 disk 驱动。
- 必须安装 Flysystem 适配器包，推荐
overtrue/flysystem-oss:^4.0（Laravel 9/10 + PHP 8.1+ 环境）；jacobcyl/ali-oss-storage等老包对 PHP 8.2+ 已停止维护，且 ServiceProvider 注册方式与新版 Laravel 冲突 - 装完后务必运行
php artisan config:clear，否则config/filesystems.php新增的ossdisk 不会被识别 - 不要手动在
config/app.php里加ServiceProvider——overtrue/flysystem-oss是 auto-discovered，Laravel 5.5+ 无需手动注册
endpoint 和 bucket 怎么填才不报 cURL 错误或 403
这两个字段写错，会导致上传静默失败、返回 false，或抛出 OSSException / cURL error 6（无法解析域名）等底层异常。
-
endpoint必须带协议，例如https://oss-cn-shenzhen.aliyuncs.com；写成oss-cn-shenzhen.aliyuncs.com或http://...（尤其非 HTTPS 场景下）会触发签名失败或连接拒绝 -
bucket只填纯桶名，如my-app-bucket；千万别填my-app-bucket.oss-cn-shenzhen.aliyuncs.com，否则路径拼接后变成双重域名，OSS 拒绝请求 - 如果用了自定义 CDN 域名（如
https://cdn.example.com），要同时设isCName => true且cdnDomain => 'https://cdn.example.com'，并确保该域名已在 OSS 控制台「域名管理」中绑定且 DNS 解析生效
上传大文件（>100MB）时内存溢出或超时怎么办
Storage::disk('oss')->put() 是流式上传，但默认走单次 HTTP 请求，不自动分片。大文件容易触发 PHP memory_limit 或 Nginx client_max_body_size 限制。
- 优先改用
putFileAs()+ 临时文件路径，避免一次性读入内存：Storage::disk('oss')->putFileAs('videos/', $request->file('video'), '20260501.mp4') - 真正需要断点续传或并发上传时，绕过 Flysystem，直接调用
overtrue/flysystem-oss底层的OssAdapter实例，调用其uploadFile()方法（接受本地文件路径，自动启用分片） - 别依赖
debug => true查大文件问题——日志只会记录最终失败，不会暴露分片过程；真要调试，得看storage/logs/laravel.log里是否出现MultipartUpload或InvalidPart关键词
最易被忽略的一点：OSS Bucket 的 ACL 默认是私有（private），Storage::url() 生成的是预签名 URL，有时效性；若前端需直传或公开访问，必须显式配置 visibility => 'public'（在 disk 配置里或 put() 第三个参数中传），否则连 GET 都会 403。
