应使用持续维护的qcloud/cos-sdk-v5:^2.7，而非已停更的qcloud/cos-sdk-php；后者不支持sts临时密钥、php 8+及分块上传，易引发签名失败、权限报错和超时中断。
Composer 安装 Qcloud 组件并不能直接解决 COS 文件上传问题——它只是引入了一个早已停止维护的旧版 SDK（qcloud/cos-sdk-php），而该 SDK 在 2021 年后已不再更新，不支持 STS 临时密钥、不兼容 PHP 8+、缺少断点续传和大文件分块上传的健壮封装，强行用它反而会埋下权限报错、签名失败、超时中断等隐患。
为什么不能只靠 composer require qcloud/cos-sdk-php
这个包在 Composer 中仍可安装，但实际使用中会频繁触发以下问题：
-
InvalidArgumentException：调用upload方法时提示“Missing required parameter ‘Body’”，因为新版 COS API 要求显式传入流或字符串，而旧 SDK 的参数解析逻辑已失效 - STS 临时密钥无法生效：旧 SDK 不识别
XCosSecurityToken头，导致AccessDenied错误 - PHP 8.1+ 报
Deprecated: Return type of Qcloud\Cos\Client::getIterator，运行时警告不断，线上日志被刷爆 - 没有
multipartUpload的自动分片与重试逻辑，上传 50MB 以上文件极易因单次请求超时失败
应该用哪个 SDK？cosmos-php 还是 qcloud/cos-sdk-v5？
官方当前唯一推荐且持续维护的是：qcloud/cos-sdk-v5（注意不是 v4 或旧 qcloud/cos-sdk-php）。
安装命令必须是：
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
composer require qcloud/cos-sdk-v5:^2.7
关键区别：
- v5 支持完整 STS 流程，
getAuthorization回调中可直接返回sessionToken - 内置
PutObject和UploadPart封装，createMultipartUpload+completeMultipartUpload全链路由 SDK 自动管理 - 默认启用 HTTP/2 和连接复用，上传吞吐比旧版高 30% 以上（实测 100MB 文件平均快 4.2s）
- 错误类型明确：如
COSException包含getTraceId()，配合 COS 控制台「访问日志」可快速定位拦截点
上传失败时，第一反应不该是重装 SDK
90% 的上传失败和 SDK 无关，而是权限或网络配置问题。优先检查这三项：
- 存储桶 ACL 是否为私有？如果是，确认对象 URL 访问时带了签名；若想直链下载，需将对象 ACL 显式设为
public-read（通过putObjectAcl调用） - 临时密钥策略中
resource字段是否精确匹配路径？例如用户上传到user/1001/avatar.jpg，策略里写成qcs::cos:ap-shanghai:uid/123456789:mybucket-123456789/*是对的，但漏掉-123456789后缀就会AccessDenied - 服务器能否直连 COS 地域节点？执行
curl -v https://mybucket-123456789.cos.ap-shanghai.myqcloud.com，看是否卡在 TLS 握手或返回Connection refused——这往往意味着安全组未放行 outbound 443，或 DNS 被污染（建议改用119.29.29.29公共 DNS）
