必须用 Composer 安装 aliyuncs/oss-sdk-php 并确保 PSR-4 自动加载，putObject() 第三个参数须为 resource（如 fopen 或 getStream），Endpoint 要带协议且 Bucket 名合法，上传后需设 ACL 为 public-read 或配置 Bucket 公共读权限。
直接用 OssClient 就能上传，但不配对环境、不处理资源类型、不校验临时文件句柄，十次有八次会卡在 fopen() 失败或返回空 URL。
必须用 composer require aliyuncs/oss-sdk-php 安装 SDK
手动拷贝 autoload.php 或把 SDK 放进 Library/Org 这类路径，会在 TP6/TP8 中触发命名空间冲突或自动加载失败。Composer 是唯一稳定方式 —— 它确保 OSS\OssClient 能被 PSR-4 正确识别。
- TP5/TP6/TP8 均支持该命令，无需额外适配
- 不要改 SDK 内部命名空间，也不要删
vendor/autoload.php的引入逻辑 - 如果项目已禁用 Composer 自动加载（如某些 TP5 手动部署包），需显式
require_once vendor/autoload.php，且必须放在OssClient实例化前
putObject() 的第三个参数必须是 resource，不是字符串路径
常见错误是传 $file->getTmpName() 字符串进去，putObject() 会静默失败或报 Invalid argument supplied for foreach()。它只接受 PHP 文件句柄（resource）。
- 正确写法：
fopen($file->getTmpName(), 'rb') - 错误写法：
$file->getTmpName()或file_get_contents()返回的 string - TP6+ 可用
$file->getStream()直接获取 stream resource，更安全 - 上传完记得
fclose()句柄，否则小概率触发 Too many open files
Endpoint 必须带协议，且不能和 Bucket 拼错域名
比如 oss-cn-hangzhou.aliyuncs.com 是非法 Endpoint；正确应为 https://oss-cn-hangzhou.aliyuncs.com。拼错会导致连接超时或 SSL handshake failed。
立即学习“PHP免费学习笔记（深入）”；
- Bucket 名称不能含下划线
_，只能是小写字母、数字、连字符- - OSS 外网访问 URL 格式固定为：
https://{bucket}.{endpoint}/{objectKey}，不是{endpoint}/{bucket}/... - 自定义域名需在 OSS 控制台绑定并开启 CNAME，且
endpoint配置要换成你的域名（如https://oss.example.com）
上传后生成的 URL 要检查是否可公开访问
默认 putObject() 上传的 Object 权限是 private，即使拼出 URL 也会返回 403。别急着存库，先 curl 测试。
- 临时方案：上传时加
['x-oss-object-acl' => 'public-read']参数 - 长期方案：在 OSS 控制台设置 Bucket 读写权限为“公共读”，或用
putObjectAcl()单独设 ACL - 若用了 CDN 或自定义域名，确认 OSS 的跨域（CORS）规则已放行 GET 请求
最易忽略的是临时文件生命周期 —— $file->getTmpName() 指向的文件在请求结束时会被 PHP 自动清理，所以 fopen() 必须在 upload 逻辑内立刻执行，不能延迟到事务提交后或队列中再读。
