必须安装 overtrue/flysystem-oss 才能使 storage::disk('oss') 正常工作，仅装 aliyuncs/oss-sdk-php 不够；需正确配置 endpoint（带 https://）、bucket（纯名称）、access_key、secret_key，并运行 php artisan config:clear。
composer require 阿里云 OSS SDK 后为什么 Storage::disk('oss') 报错？
Laravel 默认不认阿里云 OSS，装了 aliyuncs/oss-sdk-php 只是加了底层 SDK，没注册 Laravel 的 Flysystem 适配器。必须额外装 overtrue/flysystem-oss，它才是让 Storage::disk('oss') 能跑起来的桥梁。
- 不装
overtrue/flysystem-oss，只装aliyuncs/oss-sdk-php，调用Storage::disk('oss')->put(...)会直接抛InvalidArgumentException: Disk [oss] does not exist - 安装命令是
composer require "overtrue/flysystem-oss:^4.0"（Laravel 9/10 推荐用 v4；v3 对 PHP 8.1+ 有兼容问题） - 装完别忘了运行
php artisan config:clear，否则新配置可能不生效
config/filesystems.php 里 oss 磁盘配置哪些字段不能写错？
阿里云 OSS 的 endpoint、bucket、access_key 和 secret_key 四个字段必须严格对应控制台值，尤其 endpoint 容易漏掉协议或写成内网地址。
-
endpoint必须带https://，例如<a href="https://www.php.cn/link/116c87e094144d0002cff857e56a322f">https://www.php.cn/link/116c87e094144d0002cff857e56a322f</a>；写成oss-cn-hangzhou.aliyuncs.com或http://...会导致 cURL 错误 -
bucket是纯桶名，不要加.oss-cn-hangzhou.aliyuncs.com后缀，否则上传路径会变成双重域名 -
access_key和secret_key建议从 RAM 子账号获取，主账号密钥泄露风险高 - 如果用自定义域名（如
<a href="https://www.php.cn/link/ca904c1dfe5c1e4415ce964959278c45">https://www.php.cn/link/ca904c1dfe5c1e4415ce964959278c45</a>），要关掉isCName的自动判断，显式设为true，并确保 DNS 已解析且 OSS 绑定了该域名
上传文件时 Storage::disk('oss')->put() 返回 false 但没报错？
Flysystem 默认静默失败，put() 返回 false 多半是权限或网络问题，不是代码逻辑错误。
- 检查 OSS 控制台：Bucket 是否开启「公共读」？如果没开，又没配签名 URL，前端直传会 403
- 查看 Laravel 日志里的实际异常，常藏在
storage/logs/laravel.log中，关键词是OSSException或cURL error - 上传大文件（>100MB）建议改用
putFileAs()+ 分片上传中间件，原生put()容易超时或内存溢出 - 本地开发时若用 Homestead/Valet，确认系统时间是否和 NTP 同步，时间偏差 >15 分钟会导致签名失效，报
The difference between the request time and the current time is too large
生成可公开访问的 URL 为什么总是 404？
Storage::disk('oss')->url() 默认返回的是私有签名 URL（含 Expires 和 Signature 参数），不是永久链接。要公开 URL，得关签名或换方式。
- Bucket 权限设为「公共读」后，直接拼接
<a href="https://www.php.cn/link/a34335a3bede0f17a7af733b697ad848">https://www.php.cn/link/a34335a3bede0f17a7af733b697ad848</a>;最稳，比如<a href="https://www.php.cn/link/7a4127a65ee360ef0110b01a23ab04a3">https://www.php.cn/link/7a4127a65ee360ef0110b01a23ab04a3</a> - 若坚持用
url()，需在磁盘配置里加'options' => ['isPrivate' => false]，否则它默认走私有签名逻辑 - 注意路径分隔符：OSS 用正斜杠
/，Windows 开发环境用storage_path()读本地文件时路径可能是反斜杠，上传前记得用str_replace('\', '/', $path)统一
阿里云 OSS 的坑不在代码多难写，而在配置项之间互相咬合——endpoint 写错一个字符、bucket 多写个点、时间不同步几分钟，都会让整个流程卡在“看起来没问题，但就是不动”。上线前最好用真实 bucket 跑一遍完整读写链路，别只测 put() 成功就收工。
