阿里雲 OSS (Object Storage Service) 官方 SDK V2 使用命名空間,配置較繁瑣。johnlui/aliyun-oss 封裝為 Laravel 友善的 Composer 套件,提供簡潔鏈式 API。
composer require johnlui/aliyun-oss
# .env
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret
OSS_BUCKET=your-bucket-name
OSS_CDN_DOMAIN=cdn.yourdomain.com # 可選,自定義域名
// config/app.php (如未自動發現)
'providers' => [
// ...
JohnLui\AliyunOSS\AliyunOSSServiceProvider::class,
],
'aliases' => [
'AliyunOSS' => JohnLui\AliyunOSS\Facades\AliyunOSS::class,
],
php artisan vendor:publish --provider="JohnLui\AliyunOSS\AliyunOSSServiceProvider"
產生 config/aliyun-oss.php,可集中管理多 Bucket 設定。
<?php
use JohnLui\AliyunOSS\AliyunOSS;
// 方式一:Facade (需註冊 alias)
$oss = AliyunOSS::boot(
'https://' . env('OSS_ENDPOINT'),
env('OSS_ACCESS_KEY_ID'),
env('OSS_ACCESS_KEY_SECRET')
);
$oss = $oss->setBucket(env('OSS_BUCKET'));
// 上傳檔案
$result = $oss->uploadFile('images/avatar.jpg', public_path('uploads/avatar.jpg'));
if ($result) {
echo '上傳成功';
// 取得簽名 URL (私有 Bucket)
$url = $oss->getUrl('images/avatar.jpg', new DateTime('+1 hour'));
echo "簽名 URL: $url";
// 公開 Bucket 直接存取
// $url = $oss->getPublicUrl('images/avatar.jpg');
} else {
echo '上傳失敗: ' . $oss->getError();
}
// 刪除檔案
$oss->deleteObject('images/old.jpg');
// 列出檔案
$list = $oss->listObjects('images/', ['max-keys' => 100]);
foreach ($list as $obj) {
echo $obj['Key'] . ' - ' . $obj['Size'] . ' bytes' . PHP_EOL;
}
// 檢查檔案是否存在
if ($oss->objectExists('images/avatar.jpg')) { ... }
// 複製檔案
$oss->copyObject('source/key', 'dest/key');
// 取得檔案元資料
$meta = $oss->getObjectMeta('images/avatar.jpg');
若想使用 Laravel 統一 Storage::disk('oss') 介面,需安裝 Flysystem OSS 適配器:
composer require league/flysystem-aws-s3-v3
// 或專用 OSS 適配器
composer require iidestiny/laravel-filesystem-oss
// config/filesystems.php
'disks' => [
'oss' => [
'driver' => 'oss',
'access_id' => env('OSS_ACCESS_KEY_ID'),
'access_key' => env('OSS_ACCESS_KEY_SECRET'),
'bucket' => env('OSS_BUCKET'),
'endpoint' => env('OSS_ENDPOINT'),
'cdn_domain' => env('OSS_CDN_DOMAIN'),
'ssl' => true,
'visibility' => 'public', // 或 private
],
],
// 使用
Storage::disk('oss')->put('file.txt', '內容');
Storage::disk('oss')->url('file.txt'); // 自動產生簽名或公開 URL
| 問題 | 解決 |
|---|---|
| 簽名不匹配 | 檢查 AccessKey/Secret、Endpoint 是否匹配 Bucket 所在地域、系統時間是否同步 |
| 上傳大檔案失敗 | 啟用分片上傳 $oss->setMultipartUpload(true)、調整 PHP memory_limit、max_execution_time |
| CDN 域名 HTTPS 證書錯誤 | 確認 CDN 已配置 SSL 憑證、或使用 OSS 原生域名 |
| 權限拒絕 | RAM 子賬號需具備 OSS 權限 (AliyunOSSFullAccess 或自訂策略) |
johnlui/aliyun-oss 提供極簡 API 上傳、下載、管理 OSS 物件。配合 Laravel Filesystem 整合,可無縫替換本地/雲端儲存,符合十二因子應用原則。