OSS-Laravel-v2

基于 阿里云 OSS SDK v2 的 Laravel Filesystem 适配器，让你可以在 Laravel 中像操作本地文件系统一样操作阿里云 OSS。

注意：本项目目前处于早期开发阶段（v0.0.1），仅实现了部分常用功能，仅供个人使用。欢迎提 PR 一起完善！

环境要求

• PHP >= 8.4
• Laravel >= 13.0

安装

composer require mowangjuanzi/oss-laravel-v2

由于本包已配置 Laravel 自动发现（auto-discovery），安装后即可直接使用，无需手动注册 ServiceProvider。

配置

在 config/filesystems.php 的 disks 数组中添加新的 OSS 磁盘配置：

'oss' => [
    'driver'     => 'oss-v2',
    'access_key' => env('OSS_ACCESS_KEY'),
    'secret_key' => env('OSS_SECRET_KEY'),
    'region'     => env('OSS_REGION'),
    'endpoint'   => env('OSS_ENDPOINT'),
    'bucket'     => env('OSS_BUCKET'),
],

然后在 .env 文件中配置对应的环境变量：

OSS_ACCESS_KEY=your-access-key-id
OSS_SECRET_KEY=your-access-key-secret
OSS_REGION=cn-hangzhou
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_BUCKET=your-bucket-name

配置项说明

使用示例

配置完成后，你可以像使用其他 Laravel 存储磁盘一样使用 OSS：

use Illuminate\Support\Facades\Storage;

// 上传文件
Storage::disk('oss')->put('path/to/file.txt', 'Hello, OSS!');

// 获取文件内容
$content = Storage::disk('oss')->get('path/to/file.txt');

// 读取 JSON 文件
$data = Storage::disk('oss')->json('path/to/data.json');

// 判断文件是否存在
if (Storage::disk('oss')->exists('path/to/file.txt')) {
    // 文件存在
}

// 判断文件是否不存在
if (Storage::disk('oss')->missing('path/to/file.txt')) {
    // 文件不存在
}

如果希望将 OSS 设为默认磁盘，可以在 config/filesystems.php 中修改 default 为 oss，之后可直接使用 Storage::put() 等静态方法。

已支持的方法

暂未实现的方法

以下方法暂未实现，调用时会抛出 OssLaravelException 异常：

• delete / deleteDirectory
• copy / move
• directories / files / allFiles / allDirectories
• size / lastModified / mimeType / visibility
• makeDirectory
• readStream / writeStream
• 等其他高级文件操作

License

本项目基于 MIT 协议开源。

贡献

如果你在使用过程中遇到问题或希望新增功能，欢迎：

• 提交 Issue
• 提交 Pull Request

大家一起完善这个项目 💪