必须同时安装 aliyuncs/oss-sdk-php 和 league/flysystem-aliyun-oss-driver，因后者仅为适配器，核心功能（http 请求、签名、分片上传）依赖前者；单独安装 adapter 会导致 class 'aliyunoss\ossclient' not found 错误。
composer 安装 oss-sdk 和 flysystem-adapter 为什么必须配对
不装 aliyuncs/oss-sdk-php，league/flysystem-aliyun-oss-driver 就跑不起来——后者只是个适配器，真正发 HTTP 请求、处理签名、分片上传的逻辑全在 SDK 里。常见错误是只装了 adapter，结果一调 Storage::put() 就报 Class 'AliyunOSS\OssClient' not found。
实操建议：
- 用
composer require aliyuncs/oss-sdk-php league/flysystem-aliyun-oss-driver一起装，别分开 - Laravel 9+ 默认用 Flysystem v3，必须选
league/flysystem-aliyun-oss-driver:^4.0，否则OssAdapter类找不到 - 如果项目已存在
flysystemv2（比如 Laravel 8），强行升 v3 会触发FilesystemAdapter构造参数不兼容
config/filesystems.php 里写 oss 磁盘时 endpoint 怎么选
endpoint 写错是最常见的上传失败原因，不是域名不通，而是签名算出来被 OSS 服务端拒绝。阿里云 OSS 的 endpoint 分三类：公共云地域域名、内网域名、自定义绑定域名，但 Laravel 配置里只认「地域域名」格式，且必须带协议。
实操建议：
- 用
https://oss-cn-hangzhou.aliyuncs.com这种格式，不能写oss-cn-hangzhou.aliyuncs.com（缺协议） - 不能用 bucket 绑定的自定义域名（如
https://static.example.com），OSS SDK 不支持用自定义域名做签名计算 - 内网 endpoint（如
https://oss-cn-hangzhou-internal.aliyuncs.com）仅限 ECS 同地域访问，本地开发配了也连不上 - 华东 1（杭州）是
oss-cn-hangzhou，不是oss-hangzhou或oss-cn-zhejiang——地域 ID 必须严格匹配阿里云控制台显示的值
env 文件里 ACCESS_KEY_SECRET 被自动截断怎么办
阿里云的 ACCESS_KEY_SECRET 可能含斜杠 /、加号 +、等号 =，而 Laravel 的 env() 解析器会把 + 当空格、把 = 当键值分隔符，导致密钥变短，签名直接失败，错误现象是 InvalidAccessKeyId 或 SignatureDoesNotMatch。
实操建议：
- 在
.env里给密钥加英文双引号，例如：ALIYUN_OSS_SECRET="LTAI5tQZxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX" - 不要用单引号——Laravel 的
env()不解析单引号内的转义 - 如果密钥里有换行或制表符（比如从某些密码管理器复制），直接重生成一对新 AK/SK 更省事
上传大文件时 timeout 或 504 错误怎么调
默认配置下，PHP 的 max_execution_time、Nginx 的 proxy_read_timeout、OSS SDK 的 timeout 参数三者只要一个超时，就会中断上传。尤其是分片上传（>100MB），SDK 会发多个请求，总耗时不可控。
实操建议：
- 在
config/filesystems.php的 oss 磁盘配置里显式设'timeout' => 300（单位秒） - PHP-FPM 需同步调大
request_terminate_timeout和request_slowlog_timeout - Nginx 配置里加：
proxy_connect_timeout 300;、proxy_send_timeout 300;、proxy_read_timeout 300; - 别依赖
ini_set('max_execution_time', 0)—— CLI 模式有效，FPM 下会被 php-fpm 配置强制覆盖
endpoint 格式、密钥转义、超时链路这三处，改错一个就卡死，而且错误信息都指向“权限”或“网络”，容易误判。实际八成问题出在这三块配置上，而不是代码逻辑。
