Laravel原生S3驱动无法直连阿里云OSS，因签名算法、endpoint格式、region命名及ACL处理均与AWS不兼容；必须用overtrue/flysystem-oss扩展并配置driver为'oss'，否则报Disk[oss]不存在或SignatureDoesNotMatch。
直接用 Laravel 的 Storage 门面对接云存储，不是改几个环境变量就能跑通的事。S3、OSS、COS 表面都叫“兼容 S3”，但签名方式、endpoint 解析逻辑、path style 要求、ACL 默认行为全都不一样。配错一个参数，put() 静默返回 false，url() 拼出 404 链接，或者报 SignatureDoesNotMatch 这类错误，根本看不出哪错了。
为什么 disk('s3') 连不上阿里云 OSS
Laravel 原生 s3 驱动只认 AWS 规范：它默认用子域名格式（bucket.s3.region.amazonaws.com）拼 endpoint，并依赖 v4 签名的特定 header 注入顺序。阿里云 OSS 要求：use_path_style_endpoint=true，region 必须填 oss-cn-hangzhou（不能是 cn-hangzhou），且 AWS_ENDPOINT 必须是带协议的完整地址（如 https://oss-cn-hangzhou.aliyuncs.com）。
即使你强行补全这些，Laravel 8.77+ / 9.x 才支持 AWS_USE_PATH_STYLE_ENDPOINT，低版本会忽略该配置；更麻烦的是，OSS 的 PutObject ACL 默认是私有，而 Laravel s3 驱动不自动加 x-amz-acl: public-read，结果文件上传成功但前端访问 403。
-
AWS_DEFAULT_REGION填错地域（比如把oss-cn-shenzhen写成cn-shenzhen）→ 报InvalidAccessKeyId -
AWS_ENDPOINT漏掉https://→ cURL error 6 或 403 - 没设
'options' => ['acl' => 'public-read']→ 文件存在但无法直链访问
配 OSS 必须用 driver => 'oss'，不是 's3'
社区主流方案是 overtrue/flysystem-oss，它封装了阿里云 SDK 并适配 Flysystem 接口。只装 aliyuncs/oss-sdk-php 不行，那只是底层 SDK，没注册 Laravel 的磁盘驱动。
装完后要在 config/filesystems.php 新增磁盘，driver 字段必须写 'oss'，否则 Storage::disk('oss') 直接抛 Disk [oss] does not exist。
- 确保
composer require "overtrue/flysystem-oss:^4.0"（Laravel 9/10 推荐 v4） -
access_key和secret_key务必从 RAM 子账号获取，别用主账号密钥 -
endpoint从 OSS 控制台「Bucket 域名」区域复制「外网访问域名」，带https:// -
bucket填纯名称（如my-bucket），不要拼 endpoint 后缀 -
root是 Bucket 内路径前缀（如uploads/），不是服务器目录
put() 返回 false 却没异常？先查日志和权限
Flysystem 默认失败不抛异常，put() 返回 false 是最典型的静默失败信号。别急着改代码，先看 storage/logs/laravel.log 里有没有 OSSException 或 cURL error 关键词。
OSS 控制台也要同步检查：Bucket 是否开启「公共读」？RAM 策略是否允许 oss:PutObject 且 Resource 匹配你的 bucket 和 prefix？如果用自定义 CDN 域名，cdn_domain 配置了没？DNS 解析和 OSS 绑定是否完成？
- 上传内容必须是字符串或 resource：
put('a.jpg', file_get_contents($path))，不是put('a.jpg', $path) - 大文件（>100MB）慎用
put()，容易超时或内存溢出，应走分片上传 - 本地开发用 Homestead/Valet，系统时间偏差 >15 秒会导致签名过期，需同步 NTP
url() 生成的链接打不开？检查 url 和 cdn_domain 配置
OSS 磁盘的 url() 方法默认拼的是 endpoint + bucket + path，但如果你开了 CDN 或自定义域名，这个链接就失效了。必须显式配置 cdn_domain，并确保 url 字段指向正确入口。
例如，OSS 控制台绑定了 https://cdn.example.com，那 config/filesystems.php 里就得写：
'oss' => [
'driver' => 'oss',
'cdn_domain' => 'https://cdn.example.com',
'url' => 'https://cdn.example.com',
// 其他字段...
],
- 没配
cdn_domain，url()就按 OSS endpoint 拼，可能跨域或被拦截 -
url字段必须和cdn_domain一致，否则Storage::url()返回的还是 OSS 原始地址 - 若用内网 endpoint（如
http://oss-cn-hangzhou-internal.aliyuncs.com），url()生成的链接前端无法访问，必须配公网或 CDN
真正卡住人的从来不是“怎么配”，而是“哪个字段在哪个环节起作用”。endpoint 格式影响连接，ACL 影响可读性，cdn_domain 影响最终 URL，三者缺一不可，且各自生效位置不同——改完 config 别忘了 php artisan config:clear，缓存不刷，新配置就是不生效。
