应改用 cos-php-sdk-v5（无 qcloud/ 前缀），升级至 ^5.7+ 版本，确保 PHP ≥7.2 且兼容 8.1+，正确配置 region、credentials 及 token（如需），避免使用废弃包 qcloud/cos-sdk-v5。
composer require qcloud/cos-sdk-v5 报错：package not found
不是 SDK 被下架了，而是 qcloud/cos-sdk-v5 从 2021 年起就**不再维护**，官方已归档，Packagist 上也标记为 abandoned。Composer 默认不安装废弃包，除非显式允许。
- 必须加
--with-all-dependencies或降级 Composer 版本（不推荐） - 更稳妥的做法是改用官方主推的
cos-php-sdk-v5—— 注意名字里没有qcloud/前缀，这是腾讯云迁移后的正式包名 - 如果项目还依赖旧版签名逻辑（如
qcloudapi风格），得同步检查CosClient初始化参数是否兼容
PHP 8.1+ 环境下 cos-php-sdk-v5 初始化失败
新版 cos-php-sdk-v5 默认要求 PHP >= 7.2，但部分早期 v5.x 小版本（如 5.6.1）对 PHP 8.1 的 mbstring.func_overload 兼容有问题，会触发 Deprecated: mb_ereg_replace(): Passing null to parameter #3 ($replacement) of type string is deprecated 类错误。
- 优先升级到
cos-php-sdk-v5:^5.7或更高（截至 2024 年最新稳定版是 5.7.12） - 确认
ext-curl和ext-json已启用，SDK 不依赖ext-openssl但 HTTPS 上传必须有它 - 别直接 new CosClient；要用
new \Qcloud\Cos\Client($options)，且$options['region']必须是字符串（如'ap-beijing'），不能是空格或下划线拼接的旧写法
上传文件时提示 “SignatureDoesNotMatch” 或 “InvalidAccessKeyId”
这基本不是 SDK 问题，而是凭证配置或签名上下文不一致导致的。v5 SDK 使用的是 V4 签名，但控制台生成的临时密钥、STS Token、甚至某些子账号 SecretId/SecretKey 都可能因权限策略限制无法完成完整签名流程。
-
$options['credentials']必须传数组，格式为['secretId' => 'xxx', 'secretKey' => 'yyy']，字段名大小写敏感，不能写成SecretId - 若用临时密钥，
$options中必须额外带'token' => 'zzz'，漏掉就会签出无效签名 - Region 写错也会间接导致签名失败——比如桶在
ap-guangzhou，却配成ap-shanghai，后端校验时域名和签名预设 region 对不上
用 GuzzleHttpAdapter 自定义 HTTP 客户端失败
v5 SDK 底层默认用 cURL，但支持通过 'http_handler' 注入自定义 Handler（比如用 Guzzle）。不过直接传 new \GuzzleHttp\Client() 会报 Argument 1 passed to Qcloud\Cos\Http\GuzzleHttpAdapter::__construct() must be an instance of GuzzleHttp\Ring\Client —— 因为 SDK v5 绑定的是 RingPHP 时代的老版 Guzzle（guzzlehttp/ringphp），不是现在的 guzzlehttp/guzzle。
- 不要强行注入现代 Guzzle 实例；要么保持默认 cURL，要么用 SDK 自带的
Qcloud\Cos\Http\CurlHandler - 真要换 HTTP 库，建议升到
cos-php-sdk-v6（需 PHP 8.0+），它原生支持 PSR-18，可自由接入任何兼容客户端 - 调试时可在
$options['http_options']['debug'] = true开启底层请求日志，比自己套一层 Guzzle 更快定位问题
Region 和凭证是硬性匹配项，改错一个，后面所有操作都白搭；SDK 版本号看着只差一位，但签名逻辑、异常类命名、甚至返回结构都可能不兼容。
