直接使用 Qcloud\Cos\Client 最可控，需严格匹配 region、带 appid 的 Bucket 名，上传用 fopen 句柄避免内存溢出，下载优先用 SaveAs 或流式输出；ThinkPHP Storage 封装易因配置缺失或格式错误导致静默失败。
直接用 Qcloud\Cos\Client 读写文件最可控
不依赖框架封装，能明确控制上传/下载行为、错误处理和超时逻辑。尤其适合需要自定义 Key 命名规则、设置元数据、或处理大文件分块的场景。
常见错误现象：Client 初始化失败报 Invalid region 或 SignatureDoesNotMatch；putObject 报 403 Forbidden；getObject 返回空内容但 HTTP 状态码是 200。
- 确保
region值与 COS 控制台里桶的地域完全一致（如ap-shanghai，不能写成shanghai或cn-shanghai） -
Bucket必须带 appid 后缀，格式为my-bucket-1250000000，漏掉 appid 会导致鉴权失败 - 上传本地文件用
Body参数传fopen($localPath, 'rb')资源句柄，别直接传字符串内容，否则大文件会爆内存 - 下载时用
SaveAs指定本地路径，或用Body字段读取返回流，避免用body（小写）——SDK 只认大写Body
putObject 和 getObject 的参数差异必须盯紧
这两个是最常用方法，但签名逻辑和参数校验严格，拼错一个键名或类型就静默失败。
使用场景：上传用户头像、下载日志归档、同步配置文件。
立即学习“PHP免费学习笔记（深入）”；
-
putObject必填Bucket、Key、Body；可选ACL（如public-read）、ContentType（建议显式设为image/jpeg等，否则默认binary/octet-stream） -
getObject必填Bucket、Key；若要保存到本地，必须传SaveAs字符串路径；若要读取内容，从返回值的Body字段取（它是Psr\Http\Message\StreamInterface实例） - 不要把
Key写成绝对路径（如/images/xxx.jpg），COS 不认开头的/，应写成images/xxx.jpg
ThinkPHP 用 Storage::disk('cos') 时配置容易漏项
看似一行代码就能读写，但底层依赖 qcloud/cos-sdk-v5，一旦配置缺字段或格式错，put 不报错但文件没上传成功，get 返回 null。
性能影响：每次调用都会新建 SDK 客户端实例（除非你手动复用），高并发下可能触发连接池耗尽。
-
config/filesystem.php中disks.cos.bucket必须是完整桶名（含 appid），不是控制台显示的“简称” -
disks.cos.region值要和endpoint匹配；如果填了endpoint，region可为空，但二者不能冲突 - 上传二进制内容时，
Storage::disk('cos')->put('a.jpg', file_get_contents('local.jpg'))会把整个文件读进内存，大文件慎用；改用fopen流式传入更稳
下载大文件别用 getObject 直接读内存
当文件超过几 MB，用 $result['Body']->getContents() 容易 OOM，特别是 PHP 内存限制没调高的时候。
容易踩的坑：前端请求下载 COS 文件却卡死、Nginx 报 504 Gateway Timeout、PHP-FPM worker 被 kill。
- 用
SaveAs参数让 SDK 直接写磁盘：$client->getObject(['Bucket' => $b, 'Key' => $k, 'SaveAs' => '/tmp/downloaded.zip']) - 如需边下边吐给浏览器，用
stream_copy_to_stream($result['Body'], fopen('php://output', 'w'))，并提前设好Content-Length和Content-Type - 别在 CLI 脚本里用
php://output，它会报 Warning；CLI 下一律用SaveAs或fopen('/dev/stdout', 'w')
Bucket 名称格式、region 字符串大小写、以及 Body 和 SaveAs 的二选一逻辑里——这些地方错一点，表现都是“没反应”或“空结果”，而不是明显报错。 
