核心是用 overtrue/flysystem-qiniu 替代已废弃的 league/flysystem-qiniu，bucket 全小写无区域后缀，accesskey/secretkey 须从密钥管理复制，上传时必须用 $file->getrealpath() 获取路径再 file_get_contents() 读取内容，大文件应绕过 flysystem 直接用 qiniu sdk 分片上传。
ThinkPHP 文件上传到七牛云，核心是用正确的 SDK、配对的参数、适配的文件读取方式。不同 ThinkPHP 版本（3.2 / 5.x / 6.x / 7.x）写法有差异，但底层逻辑一致：生成上传凭证 → 调用七牛 SDK 上传 → 获取可访问 URL。
确认 SDK 和驱动版本
官方 league/flysystem-qiniu 已废弃，新版必须用 overtrue/flysystem-qiniu（基于七牛 v7+ SDK）。安装命令：
composer require overtrue/flysystem-qiniu- 确保
qiniu/php-sdk同时存在（overtrue包已自动依赖）
若用原生 SDK（推荐大文件或需精细控制），直接装：composer require qiniu/php-sdk
配置项必须严格校验
以下字段在 config/filesystems.php（TP6/7）或 config.php（TP3.2/5）中填写，任何一项错误都会导致上传失败：
-
bucket：全小写，不带区域后缀（如
my-images✅，my-images-z2❌） - accessKey / secretKey：从七牛「密钥管理」页面复制，不是对象存储临时 Token
-
region：按空间所在区域填（华东
z1、华南z2、华北z3等） -
domain：必须与七牛控制台「空间域名」完全一致，含协议（如
https://cdn.example.com） -
useHttps：建议设为
true，避免混合内容警告
上传代码写法（以 TP6 为例）
关键点：不能直接传 $file 对象，要读取二进制内容。
- 使用 Flysystem（适合中小文件）：
（需先配置好 qiniu 磁盘）
use think\facade\Filesystem;
$file = $this->request->file('image');
$content = file_get_contents($file->getRealPath()); // 必须这样读
$key = 'uploads/' . uniqid() . '.' . $file->getOriginalExtension();
Filesystem::disk('qiniu')->put($key, $content);
$url = Filesystem::disk('qiniu')->url($key); // 返回完整 CDN 地址
- 使用原生 Qiniu SDK（适合 >10MB 大文件或需分片）：
use Qiniu\Auth;
use Qiniu\Storage\UploadManager;
$auth = new Auth($accessKey, $secretKey);
$token = $auth->uploadToken($bucket);
$uploadMgr = new UploadManager();
list($ret, $err) = $uploadMgr->putFile($token, $key, $file->getRealPath());
if ($err !== null) {
// 处理错误
}
$url = $domain . '/' . $ret['key'];
常见报错及修复
- Invalid bucket name：检查 bucket 是否含大写、短横、区域后缀；确认没误填 endpoint
-
File not found: /tmp/phpXXXXXX：不要用
$file->getPathname()，改用$file->getRealPath()；OPcache/Swoole 环境下若返回 false，fallback 到$file->read() - 鉴权失败 / SignatureDoesNotMatch：AK/SK 是否从「密钥管理」复制？是否混用了临时 Token？时间是否严重偏差？
-
空文件 / 上传后损坏：确认
file_get_contents()读取成功，且未被open_basedir限制
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
