正确做法是统一走Composer自动加载，执行composer require qiniu/php-sdk:^7.0，确保vendor/autoload.php已在public/index.php中引入，避免手动require导致Class not found；bucket名须为纯名称（不含-z1等后缀），region需单独配置，URL拼接须用已备案并启用的CDN域名且协议匹配。
直接用 composer require qiniu/php-sdk 安装官方 SDK，再配合 ThinkPHP 的 request()->file() 获取上传文件路径，就能完成基础上传——但必须注意 putFile() 传的是本地磁盘路径，不是内存流，且 bucket 名不能带区域后缀（如 -z1）。
为什么 vendor/qiniu/autoload.php 手动引入会报错？
ThinkPHP 5.0.20 默认不自动加载第三方库的 autoload。手动 require 虽然能跑通，但容易因命名空间冲突或重复加载导致 Class 'Qiniu\Auth' not found。
- 正确做法是统一走 Composer 自动加载：执行
composer require qiniu/php-sdk:^7.0（SDK v7+ 是当前唯一维护版本） - 确认
vendor/autoload.php已在入口文件public/index.php中被引入（TP5.0.20 默认已包含） - 不要把 SDK 拷进
vendor/Qiniu/手动管理，否则 Composer 不识别，use Qiniu\Auth会失败
上传时 putFile() 报 Invalid bucket name 怎么办？
这是最常踩的坑：七牛控制台显示的 bucket 名可能是 my-bucket-z2，但 SDK 要求的 bucket 参数必须是纯名称（my-bucket），区域信息应通过 region 配置项单独传入。
-
bucket值必须全小写、不含-z1/-cn-east-1等后缀 - 若使用 SDK v7+，需显式指定
region（如z2表示华南节点），否则默认z1（华东），鉴权可能失败 - accessKey / secretKey 务必从七牛「密钥管理」页面复制，不能用对象存储临时 Token
怎样把 think\File 对象传给 putFile()？
putFile() 第三个参数必须是可读的本地文件路径（string），不是 think\File 实例，也不是 $_FILES 数组。
立即学习“PHP免费学习笔记（深入）”；
- 用
$file->getRealPath()获取临时文件绝对路径（例如/tmp/phpabc123） - 避免用
$file->getPathname()——它返回的仍是/tmp/phpxxx，但某些环境（如 Swoole 或 open_basedir 限制）下会被拒绝读取 - 如果
getRealPath()返回false（常见于 Swoole 或 OPcache 启用时），fallback 到$file->read()+put()（需改用UploadManager::put()接收二进制内容）
上传成功后怎么拼出可访问的 URL？
SDK 本身不生成 URL，要靠你自己拼接。关键点是：域名必须和七牛控制台「空间设置 → 域名管理」里备案并启用的 CDN 域名完全一致，且协议要匹配（http:// 或 https://）。
- 不要用
bucket.qiniudn.com这类旧域名（已停用） - 不要漏掉
https://前缀，否则前端加载会因混合内容被浏览器拦截 - key 值不能以
/开头，否则 URL 会多出一层路径（如https://cdn.example.com//uploads/xxx.jpg）
真正卡住人的地方往往不是代码逻辑，而是 bucket 名混用了控制台显示的“完整标识”，或是 CDN 域名没在七牛后台完成 ICP 备案并开启 HTTPS；这些配置错误不会报 PHP 异常，只会静默失败或返回 404。
