萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

Laravel 整合阿里雲 OSS 儲存 (Composer 套件 johnlui/aliyun-oss)

前言

阿里雲 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 # 可選,自定義域名

服務提供者註冊 (Laravel 5.5+ 自動發現)

// 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 Filesystem (Flysystem)

若想使用 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 整合,可無縫替換本地/雲端儲存,符合十二因子應用原則。

copyright © 萬盛學電腦網 all rights reserved