Laravel 整合阿里雲 OSS Composer 套件：johnlui/aliyun-oss 使用教學

阿里雲官方 SDK V2 雖功能完整但使用門檻較高。本文介紹社群維護的 johnlui/aliyun-oss Composer 套件，提供簡潔 API 封裝，幾行程式碼即可完成上傳、下載、簽名 URL 生成等核心操作。

安裝套件

# 專案根目錄執行
composer require johnlui/aliyun-oss

# 或手動編輯 composer.json
{
    "require": {
        "johnlui/aliyun-oss": "dev-master"
    }
}
composer update

核心配置參數

基本使用範例

<?php
use JohnLui\AliyunOSS\AliyunOSS;

// 1. 建立客戶端 (通常在 ServiceProvider 中註冊為單例)
$oss = AliyunOSS::boot(
    'https://oss-cn-hangzhou.aliyuncs.com', // Endpoint (含 https://)
    env('OSS_ACCESS_KEY_ID'),               // AccessKeyId
    env('OSS_ACCESS_KEY_SECRET')            // AccessKeySecret
);

// 2. 設定 Bucket
$oss = $oss->setBucket(env('OSS_BUCKET'));

// 3. 上傳本地檔案
// 參數：物件名稱 (OSS 中的路徑)、本地檔案路徑
$result = $oss->uploadFile('avatars/user_123.jpg', storage_path('app/public/avatar.jpg'));

if ($result) {
    echo "上傳成功！";
} else {
    echo "上傳失敗：" . $oss->getError();
}

// 4. 產生簽名下載 URL (私有 Bucket 必須)
// 參數：物件名稱、過期時間 (DateTime 物件)
$downloadUrl = $oss->getUrl('avatars/user_123.jpg', new DateTime('+1 hour'));
echo "下載連結：$downloadUrl";

// 5. 刪除檔案
$oss->deleteObject('avatars/user_123.jpg');

// 6. 列舉檔案
$list = $oss->listObjects('avatars/');
foreach ($list as $object) {
    echo $object['Key'] . ' - ' . $object['Size'] . ' bytes' . PHP_EOL;
}

Laravel 整合最佳實踐

1. 設定檔 config/filesystems.php (推薦)

'disks' => [
    'oss' => [
        'driver' => 'oss',
        'access_key_id' => env('OSS_ACCESS_KEY_ID'),
        'access_key_secret' => env('OSS_ACCESS_KEY_SECRET'),
        'bucket' => env('OSS_BUCKET'),
        'endpoint' => env('OSS_ENDPOINT'), // 如 oss-cn-hangzhou.aliyuncs.com
        'region' => env('OSS_REGION'),     // 如 cn-hangzhou
        'url' => env('OSS_PUBLIC_URL'),    // 自定義域名/CDN 域名 (可選)
    ],
],

2. 服務提供者註冊 AppServiceProvider

use JohnLui\AliyunOSS\AliyunOSS;
use Illuminate\Support\Facades\Storage;

public function boot() {
    // 註冊自定義驅動
    Storage::extend('oss', function ($app, $config) {
        $oss = AliyunOSS::boot(
            'https://' . $config['endpoint'],
            $config['access_key_id'],
            $config['access_key_secret']
        );
        return $oss->setBucket($config['bucket']);
    });
}

3. 統一使用 Storage Facade

use Illuminate\Support\Facades\Storage;

// 上傳
Storage::disk('oss')->put('files/report.pdf', $pdfContent);

// 取得 URL (公開讀取 Bucket)
$url = Storage::disk('oss')->url('files/report.pdf');

// 臨時簽名 URL (私有 Bucket)
$url = Storage::disk('oss')->temporaryUrl(
    'files/report.pdf', 
    now()->addHour()
);

// 刪除
Storage::disk('oss')->delete('files/report.pdf');

進階功能

• 分塊上傳：大檔案 (＞100MB) 使用 uploadFileByPart()
• 圖片處理：OSS 影像處理參數 ?x-oss-process=image/resize,w_200
• 生命週期：設定自動轉冷存儲/刪除規則
• 防盜鏈：Referer 白名單設定
• 跨域 CORS：允許瀏覽器直傳

常見問題排查

專案連結

• GitHub：https://github.com/johnlui/AliyunOSS
• Packagist：johnlui/aliyun-oss