class "qcloud\cos\client" not found 是因 sdk 未正确安装或依赖扩展缺失；需启用 ext-simplexml、ext-json，使用 composer require qcloud/cos-sdk-v5:^2.6，并确保自动加载生效。
PHP 8.5 调用腾讯云 COS SDK 报 Class "Qcloud\Cos\Client" not found
这是最常见问题：SDK 没装对，或自动加载失效。PHP 8.5 已移除 ext-xmlrpc 和部分旧扩展，但腾讯云官方 SDK（cos-php-sdk-v5）仍依赖 ext-simplexml 和 ext-json —— 这两个必须启用，否则连类都载不进来。
- 确认已运行
composer require qcloud/cos-sdk-v5:^2.6（^2.6是目前兼容 PHP 8.5 的最新稳定版，^2.5在 PHP 8.5 下有mbstring函数签名警告） - 检查
php -m | grep -E "(simplexml|json|mbstring)"，缺哪个就装哪个（腾讯云 CVM 默认已全开，但自编译 PHP 容易漏simplexml） - 别手动 require 类文件；Composer 自动加载机制必须生效，确保项目根目录有
vendor/autoload.php且已引入
上传文件时提示 InvalidRequest: The body of your POST request is not well-formed XML.
这通常不是网络或权限问题，而是 SDK 初始化参数写错了 —— 尤其是 region 和 bucket 拼接逻辑在 PHP 8.5 + SDK v2.6 下更严格了。
-
bucket必须是完整格式："my-bucket-1250000000"（含 APPID 后缀），不能只写"my-bucket" -
region必须用短名，如"ap-beijing"，不能写"北京"或"cn-north" - SecretId / SecretKey 必须是字符串类型，如果从环境变量读取，确保没带换行符或空格（建议用
trim()包一层） - 示例初始化片段：
$cosClient = new Qcloud\Cos\Client([ 'region' => 'ap-beijing', 'schema' => 'https', 'credentials' => [ 'secretId' => trim($_ENV['COS_SECRET_ID']), 'secretKey' => trim($_ENV['COS_SECRET_KEY']), ], ]);
用 putObject 传大文件卡住或内存溢出
PHP 8.5 默认禁用 allow_url_fopen，而 SDK 的流式上传底层会尝试用 fopen("https://...") 回退机制 —— 一旦失败就降级成全内存读取，10MB 文件就可能吃光 256MB 内存限制。
- 上传 >2MB 的文件，强制走分块上传：
upload方法代替putObject，它自动切片、并发、断点续传 - 务必设置
PartSize（默认 5MB），大文件建议设为10485760（10MB），避免切太碎触发 COS 频率限流 - 示例：
$result = $cosClient->upload( 'my-bucket-1250000000', 'path/to/file.zip', fopen('/tmp/file.zip', 'rb'), ['PartSize' => 10485760] ); - 别用
file_get_contents()读大文件再传 —— PHP 8.5 对超大字符串处理更敏感，容易触发 OOM 或 GC 延迟
本地测试能传，上腾讯云 CVM 就超时或 403
不是 SDK 问题，是 CVM 实例的元数据服务（IMDS）和 COS 权限耦合导致的静默失败。很多用户开了 CAM 角色但没配策略，或用了错误的 endpoint。
立即学习“PHP免费学习笔记（深入）”；
- 检查是否误用了内网 endpoint：
cos.ap-beijing.myqcloud.com是公网地址，CVM 内网应优先用cos.ap-beijing.tencentcos.cn（注意后缀是tencentcos.cn，不是myqcloud.com） - CAM 角色策略必须显式授权
name/cos:PutObject，仅给QcloudCOSFullAccess策略在某些新地域可能不生效 - 如果用临时密钥（STS），
token字段必须传进credentials，漏掉就会 403：'credentials' => [ 'secretId' => $tmpSecretId, 'secretKey' => $tmpSecretKey, 'token' => $tmpToken, // ← 这行不能少 ]
