thinkphp内置upload类无法直接上传到oss，因其filesystem默认不支持oss驱动；正确做法是实现driverinterface封装ossclient，配置oss磁盘后调用$file->store('path', 'oss')。
为什么直接用ThinkPHP内置Upload类上传不到OSS
因为 think\facade\Filesystem 默认只支持本地驱动和少量云存储（如S3），OSS不在原生支持列表里；Upload 类本身只处理HTTP请求中的文件临时保存，不负责后续上传逻辑。想让文件“上传到OSS”，本质是：先接收文件 → 再把临时文件或流写入OSS。跳过这层理解，硬套 Upload::save() 就会卡在本地路径报错。
- 常见错误现象：
File not found: /tmp/phpXXXXXX或Call to undefined method think\File::getRealPath()—— 说明你试图把think\File对象直接丢给没适配OSS的驱动 - 正确路径是：用
think\File接收 → 转成resource或string→ 交给自定义OSS驱动写入 - 别在控制器里手动调
ossClient->putObject()，那会绕过ThinkPHP文件系统抽象，失去统一配置、事件、中间件等能力
如何注册自定义OSS文件系统驱动
核心是实现 think\Filesystem 要求的 think\filesystem\DriverInterface，再通过 think\FilesystemManager::extend() 注入。阿里云官方SDK的 OssClient 不符合该接口，必须包一层。
- 新建类
app\driver\OssDriver，构造函数接收OssClient实例和基础参数（bucket、endpoint） - 必须实现
write($path, $contents, $options = [])：对字符串内容直接putObject；对资源句柄（如fopen($file, 'r')）需用putObjectFromStream - 注意
$path是相对路径（如uploads/avatar.jpg），OSS驱动里要拼上bucket和endpoint，但别硬编码，从配置读 - 在
app\common\provider\AppServiceProvider::register()中调用：FilesystemManager::extend('oss', function ($app) { return new OssDriver(...); });
上传时怎么让File对象走OSS驱动而不是本地
关键在 think\File 的 store() 方法——它内部会调用 Filesystem::disk()->put()，而这个 disk() 名称决定了用哪个驱动。所以不是改上传逻辑，是改「存到哪个盘」。
- 配置
config/filesystem.php，加一个磁盘配置：'oss' => ['driver' => 'oss', 'access_key_id' => 'xxx', 'access_key_secret' => 'xxx', 'bucket' => 'my-bucket', 'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com'] - 控制器里接收文件后，不要用
$file->move()，改用：$file->store('uploads', 'oss')—— 第二个参数就是磁盘名 - 如果传参是
$file->storeAs('uploads', 'abc.jpg', 'oss')，确保abc.jpg不含非法字符（OSS对object key有长度和字符限制，空格、中文、控制字符会失败） - 注意
store()返回的是相对路径（如uploads/xxx.jpg），不是完整URL；要生成可访问链接得自己拼：https://my-bucket.oss-cn-hangzhou.aliyuncs.com/ + $path
容易被忽略的权限与异常处理细节
OSS上传失败往往不是代码问题，而是配置或权限卡住，而且ThinkPHP默认不会透出OSS SDK的原始异常信息。
- Bucket必须开启「公共读」或生成带签名的临时URL；否则前端拿到链接也403——检查OSS控制台「Bucket ACL」设置
- RAM子账号需要
AliyunOSSFullAccess或最小权限策略：oss:PutObject+oss:GetObject，仅配oss:ListObjects不够 - 上传大文件（>100MB）时，
putObjectFromStream可能因超时失败，建议改用分片上传（multiupload），但这就得脱离DriverInterface简单写法，单独封装 - 务必在
OssDriver::write()里 try/catchOssException，并 throw 新的think\exception\FileException，否则ThinkPHP的异常处理器捕获不到，日志里只剩空白堆栈
真正麻烦的从来不是写驱动，是确认 endpoint 是否带 https://、bucket 名是否和 region 匹配、以及 RAM 策略里有没有漏掉 oss:PutObjectAcl —— 这些地方一错，连报错都看不出端倪。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
