ThinkPHP文件上传与云存储配置核心是先通本地上传、再切云服务：本地需确保$file->getRealPath()获取路径，避免getPathname()；云存储推荐扩展包方式配COS（bucket格式为bucket-name-appid），七牛须用overtrue/flysystem-qiniu且bucket全小写无区域后缀，OSS需选对endpoint并禁用下划线。
ThinkPHP 文件上传与云存储配置，核心在于两件事：一是把本地上传流程走通，二是让上传目标从本地磁盘切换到云服务。关键不是堆功能，而是理清路径、配对参数、避开常见坑。
本地上传先跑通
别急着连 COS 或 OSS，先确保基础上传可用。ThinkPHP 默认使用 runtime/storage 目录存文件，路径由 config/filesystem.php 中的 local 配置决定：
-
'root' => app()->getRuntimePath() . 'storage'是默认根目录，可按需改成绝对路径（如/var/www/uploads） - 上传时用
$file = $this->request->file('image')获取对象，再调$file->getRealPath()拿临时文件路径，不能直接传$file->getPathname() - 大文件（>10MB）容易超时或内存溢出，此时应跳过 Flysystem，改用云厂商 SDK 原生分片上传
对接腾讯云 COS 的三种方式
COS 配置最常卡在 bucket 格式、密钥权限和 SDK 初始化上。推荐按优先级选择：
-
扩展包方式（首选）：装
zgldh/thinkphp-cos，disks里加 cos 配置块，bucket必须写成bucket-name-1234567890（带 APPID），Region 填ap-beijing这类标准值 -
官方 SDK 手动集成：装
qcloud/cos-sdk-php，自己写 Service 类初始化Qcloud\Cos\Client，适合要控制签名、生成临时密钥或自定义上传策略的场景 - COSCLI 同步（运维向）：不走 PHP 运行时，用命令行工具批量同步静态资源，适合 CI/CD 构建后自动上传
七牛云和阿里云 OSS 的避坑要点
七牛和 OSS 看似类似，但细节差异明显，错一个参数就报错：
立即学习“PHP免费学习笔记（深入）”；
-
七牛云：必须用
overtrue/flysystem-qiniu（league/flysystem-qiniu已废弃）；bucket名全小写、不含区域后缀（如不能写my-bucket-z2）；region单独配（z2华南、z1华东）；CDN 域名必须和七牛后台备案域名完全一致 -
阿里云 OSS：SDK 用
aliyuncs/oss-sdk-php；endpoint要选对地域（如oss-cn-hangzhou.aliyuncs.com）；bucket名不能含下划线，且需提前在控制台开通并设置读写权限
统一上传逻辑与命名控制
无论存在哪，上传代码最好保持一致。建议封装一个通用方法：
- 上传前生成业务相关 key，比如
user/123/avatar/20260903_abc123.jpg，避免用纯时间戳 - 小文件走
Filesystem::disk('cos')->put($key, $content)；大文件绕过 Flysystem，直调 SDK 的uploadPart或resumableUpload - 下载链接不要硬编码，用云服务提供的签名 URL（如 COS 的
getObjectUrl、OSS 的signUrl），设置合理过期时间
