README

基于阿里云 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

配置项说明

配置项	说明	必填
`driver`	驱动名称，固定为 `oss-v2`	是
`access_key`	阿里云 AccessKey ID	是
`secret_key`	阿里云 AccessKey Secret	是
`region`	OSS 区域，如 `cn-hangzhou`	是
`endpoint`	OSS 访问端点，如 `oss-cn-hangzhou.aliyuncs.com`	是
`bucket`	OSS Bucket 名称	是

使用示例

配置完成后，你可以像使用其他 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() 等静态方法。

已支持的方法

方法	说明
`Storage::put($path, $contents)`	上传文件
`Storage::get($path)`	获取文件内容
`Storage::json($path)`	读取 JSON 文件并解析为数组
`Storage::exists($path)`	判断文件是否存在
`Storage::missing($path)`	判断文件是否不存在

暂未实现的方法

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

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

License

本项目基于 MIT 协议开源。

贡献

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

提交 Issue
提交 Pull Request

大家一起完善这个项目 💪

mowangjuanzi / oss-laravel-v2

Package info

Security

Statistics