七牛云 SDK v7+ 已移除 Qiniu\Auth，改用 Qiniu\Auth\Authorization 鉴权；需动态生成 uploadToken、检查返回 error 字段、图片处理需拼接 URL 参数或调用 pfop。
七牛云 SDK 安装后 Qiniu\Auth 找不到类
常见错误是直接 composer require qiniu/php-sdk 但没引入自动加载，或用了新版 SDK（v7+）却照抄旧文档。v7 起彻底移除了 Qiniu\Auth，改用 Qiniu\Storage\UploadManager 和 Qiniu\Auth\Authorization 分离鉴权与上传。
- 确认 SDK 版本：
composer show qiniu/php-sdk，v7.x 必须用Qiniu\Auth\Authorization - v7+ 不再支持
new Auth($accessKey, $secretKey)，改用new Qiniu\Auth\Authorization($accessKey, $secretKey) - 如果项目还在用 v6，请锁定版本：
composer require qiniu/php-sdk:^6.1，避免升级踩坑 - 别漏掉
require 'vendor/autoload.php';，尤其在非框架环境里手动引入时
上传图片时提示 401 Unauthorized 或 invalid token
绝大多数是上传凭证（upload token）生成不正确。七牛要求每次上传前都动态生成 token，不能复用、不能硬编码、不能过期（默认 3600 秒）。
- token 必须由服务端生成，前端传
accessKey/secretKey是严重安全漏洞 - 生成 token 时若指定了
scope（如bucket:key），上传时key必须严格匹配，空 key 对应bucket: - 时间戳偏差超过 15 分钟会导致签名失效，检查服务器系统时间是否同步（
ntpdate -q time.windows.com） - 示例：生成带过期时间的 token：
$token = $auth->uploadToken($bucket, $key, 3600, ['mimeLimit' => 'image/*']);
Qiniu\Storage\UploadManager::put() 上传失败但没报错信息
SDK 默认静默失败，put() 返回数组但不抛异常，必须主动检查返回值里的 error 字段。
- 永远不要只看
if ($ret)，要检查isset($ret['error'])或!empty($ret['error']) - 常见返回结构：
['hash' => 'xxx', 'key' => 'xxx']表示成功；['error' => 'xxx']才是失败 - 上传大文件（>10MB）建议用分片上传
putFile()，普通put()只适合内存中字符串或小文件资源 - 注意
put()第二个参数是$key（文件名），不是路径；七牛不识别目录结构，uploads/2024/img.jpg是合法 key，但只是名字，不是真实路径
上传后想立即加水印或缩略图，但 URL 访问还是原图
七牛的图片处理是「懒加载」的，处理指令写在 URL 里才触发，不是上传时自动转存。你得自己拼处理参数，不是靠 SDK 上传接口完成。
立即学习“PHP免费学习笔记（深入）”；
- 上传只存原始文件；访问时在 URL 后加
?imageView2/1/w/300/h/200才返回缩略图 - 水印需提前上传水印图到同 bucket，再用
?watermark/1/image/xxx拼接 - 如果希望上传后自动生成处理图并保存为新 key，得调用
pfop（持久化处理），走异步队列，不是即时返回 - 别在上传代码里写
$ret['url'] . '?imageView2/...'就完事——确保域名已绑定 CDN，且该域名在七牛控制台开启了「图片处理」开关
