如何利用ThinkPHP自定义驱动实现文件上传至阿里云OSS并管理文件系统？

本文共计930个文字，预计阅读时间需要4分钟。

由于《ThinkPHP》的`Filesystem`默认只支持本地驱动和少量云存储（如S3），COS不在原生支持列表中；`Upload`类仅处理HTTP请求中的文件临时存储，不负责后续上传逻辑。若想实现上传到OSS，本质是：

• 常见错误现象：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的原始异常信息。

立即学习“PHP免费学习笔记（深入）”；

• Bucket必须开启「公共读」或生成带签名的临时URL；否则前端拿到链接也403——检查OSS控制台「Bucket ACL」设置
• RAM子账号需要 AliyunOSSFullAccess 或最小权限策略：oss:PutObject + oss:GetObject，仅配 oss:ListObjects 不够
• 上传大文件（>100MB）时，putObjectFromStream 可能因超时失败，建议改用分片上传（multiupload），但这就得脱离 DriverInterface 简单写法，单独封装
• 务必在 OssDriver::write() 里 try/catch OssException，并 throw 新的 think\exception\FileException，否则ThinkPHP的异常处理器捕获不到，日志里只剩空白堆栈

真正麻烦的从来不是写驱动，是确认 endpoint 是否带 https://、bucket 名是否和 region 匹配、以及 RAM 策略里有没有漏掉 oss:PutObjectAcl —— 这些地方一错，连报错都看不出端倪。