README

腾讯云对象存储（OSS）Laravel 文件系统驱动

介绍

Laravel Filesystem OSS 是一个为 Laravel 应用程序提供的阿里云云对象存储。

安装

composer require i94m/laravel-filesystem-oss

配置

1. 发布配置文件（可选）

php artisan vendor:publish --provider="I94m\LaravelFilesystemOss\OssServiceProvider"

2. 配置环境变量

在 .env 文件中添加以下配置：

# 腾讯云对象存储
OSS_ACCESS_KEY_ID=
OSS_ACCESS_KEY_SECRET=
OSS_REGION=ap-guangzhou
OSS_ENDPOINT=oss-cn-guangzhou.aliyuncs.com
OSS_BUCKET=
OSS_PREFIX=
OSS_URL=

3. 配置文件系统

在 config/filesystems.php 中添加 OSS 磁盘配置：

'disks' => [
    // ... 其他磁盘配置
    'oss' => [
        'driver' => 'oss',
        'access_key_id' => env('OSS_ACCESS_KEY_ID'),
        'access_key_secret' => env('OSS_ACCESS_KEY_SECRET'),
        'region' => env('OSS_REGION'),
        'endpoint' => env('OSS_ENDPOINT'),
        'bucket' => env('OSS_BUCKET'),
        'prefix' => env('OSS_PREFIX', ''),
        'url' => env('OSS_URL'),
    ],
],

使用方法

基本文件操作

use Illuminate\Support\Facades\Storage;

// 检查文件是否存在
Storage::disk('oss')->exists('file.txt');
// 删除文件
Storage::disk('oss')->delete('file.txt');
// 写入文件
Storage::disk('oss')->put('file.txt', 'Hello World');
// 读取文件
Storage::disk('oss')->get('file.txt');
// 更新文件
Storage::disk('oss')->put('file.txt', 'Updated Content');
// 追加文件
Storage::disk('oss')->append('file.txt', 'Appended Content');
// 获取文件列表
Storage::disk('oss')->files();
// 获取文件信息
Storage::disk('oss')->getMetadata('file.txt');
// 获取文件大小
Storage::disk('oss')->size('file.txt');
// 获取文件MIME类型
Storage::disk('oss')->mimeType('file.txt');
// 获取文件最后修改时间
Storage::disk('oss')->lastModified('file.txt');

获取临时上传密钥

Storage::disk('oss')->getAdapter()->sts([
    // 前缀
    'prefix' => 'prefix/if/needed',
    // 有效期(秒)
    'expire' => 3600,
    // 最大文件大小(bytes)
    'max_file_size' => 200,
    // 上传成功后返回状态码
    'success_action_status' => 201,
]);

返回结果：

{
  "url": "https://test-2025.oss-cn-hangzhou.aliyuncs.com",
  "payload": {
    "policy": "eyJl**********",
    "x-oss-signature-version": "OSS4**********",
    "x-oss-credential": "LTAI**********",
    "x-oss-date": "20250805T061257Z",
    "x-oss-signature": "15da**********",
    "success_action_status": "201"
  }
}

参考官方文档：https://laravel.com/docs/12.x/filesystem#custom-filesystems