Laravel×S3画像アップロード完全ガイド｜Storageファサード設定・Flysystem導入から公開URL取得・IAM権限まで徹底解説

Webアプリケーションの開発において、ユーザーのプロフィール画像、記事のアイキャッチ画像、添付PDFなどのファイル保存は欠かせない機能です。

しかし、アップロードされたファイルをWebサーバーのローカルディスク（storage/app/public）に保存し続けると、「サーバーディスク容量の圧迫」「マルチサーバー・コンテナ（Docker/ECS/Kubernetes）環境でのファイル同期問題」「デプロイ時のデータ消失リスク」など多くの深刻な課題に直面します。

これらの問題を根本から解決するのが、堅牢でスケーラブルなクラウドストレージ「Amazon S3（Simple Storage Service）」の活用です。

Laravelには強力なファイルシステム抽象化レイヤーである Storageファサード（Flysystem） が標準搭載されており、ローカル環境と同じ直感的なコードでAmazon S3へのファイル保存・URL取得・削除などの操作をシームレスに実現できます。

本記事をステップ通りに進めるだけで、初心者から実務エンジニアまで、セキュアで高信頼なS3画像アップロード機能を本番環境に導入できるようになります。

1. Laravel StorageとAmazon S3の連携アーキテクチャ

Laravelのファイル操作は、PHPのオープンソースライブラリ Flysystem をベースに構築されています。これにより、保存先がローカルディスクであってもS3であっても、アプリケーションコード側は統一されたAPIで操作できます。

コントローラで Storage::disk('s3')->putFile('images', $file) を実行すると、Laravel内部でFlysystem S3アダプターが作動し、AWS SDKを通じてS3バケットの images/ランダム名.jpg にオブジェクトがアップロードされます。

2. 【AWS側の準備】S3バケット作成とIAM最小権限ポリシーの設定

LaravelからS3を利用する前に、AWSマネジメントコンソール側で 「S3バケット」 と 「プログラム実行用IAMユーザー」 を準備します。

ステップ①：S3バケットの作成

1. AWSマネジメントコンソールにログインし、Amazon S3 サービスを開きます。
2. 「バケットを作成」 ボタンをクリックします。
3. バケット名 を入力します（例: laravel-app-storage-sample ※世界中で一意である必要があります）。
4. AWSリージョン を選択します（日本国内向けサービスなら アジアパシフィック (東京) ap-northeast-1 を推奨）。
5. パブリックアクセスのブロック設定：
   • 画像をブラウザから直接URLで全体公開する場合：「パブリックアクセスをすべてブロック」のチェックを外し、承認チェックを入れます。
   • 非公開ファイル（認証ユーザー限定で一時URLを発行する場合）やCloudFront経由のみで配信する場合：「パブリックアクセスをすべてブロック」を有効のままにします。
6. 「バケットを作成」 をクリックして作成を完了します。

ステップ②：バケットポリシーの設定（画像を一般公開する場合）

アップロードした画像ファイルをWebブラウザから https://バケット名.s3.ap-northeast-1.amazonaws.com/images/xxx.jpg として誰でも直接閲覧できるようにする場合、バケットの「アクセス許可」タブの「バケットポリシー」に以下のJSONを設定します。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::laravel-app-storage-sample/*"
        }
    ]
}

※ laravel-app-storage-sample の部分は作成したご自身のバケット名に置き換えてください。

ステップ③：IAMユーザーとポリシーの作成（最小権限）

Laravelアプリケーション専用のIAMポリシーとユーザーを作成し、APIアクセスキーを発行します。

1. IAM サービスコンソールを開き、「ポリシー」→「ポリシーを作成」をクリックします。
2. 「JSON」タブを選択し、以下の必要最小限の権限を持つポリシーを記述します：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "LaravelS3BucketAccess",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::laravel-app-storage-sample"
        },
        {
            "Sid": "LaravelS3ObjectAccess",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:GetObject",
                "s3:GetObjectAcl",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::laravel-app-storage-sample/*"
        }
    ]
}

3. ポリシー名（例: LaravelS3AppStoragePolicy）を付けて保存します。
4. 「ユーザー」→「ユーザーを作成」を開き、ユーザー名（例: laravel-s3-app-user）を入力します（AWSマネジメントコンソールへのアクセス権は付与不要）。
5. 先ほど作成したポリシー（LaravelS3AppStoragePolicy）をアタッチしてユーザーを作成します。
6. 作成したユーザーの詳細画面から「セキュリティ認証情報」タブを開き、「アクセスキーを作成」 をクリックします。
7. 用途として「アプリケーションの外部で実行されるコード」を選択し、アクセスキーID（AKIA...）と シークレットアクセスキー を安全に手元へ控えます。

ステップ④：CORS（Cross-Origin Resource Sharing）設定

JavaScript（Fetch APIやCanvas）から画像を扱ったり、フォントやSPAフロントエンドからS3の画像を直接読み込む場合は、S3バケットの「アクセス許可」→「クロスオリジンリソース共有 (CORS)」に以下を設定しておきます。

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "HEAD",
            "PUT",
            "POST"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 3000
    }
]

3. 【Laravel側の初期設定】.envとfilesystems.phpの完全構築

AWS側の準備が整ったら、LaravelプロジェクトにS3ドライバパッケージを導入し、設定ファイルと環境変数を構築します。

ステップ①：Flysystem AWS S3パッケージのインストール

Laravel 9 / 10 / 11 / 12 では、S3を利用するために公式のFlysystem v3アダプターが必要です。Composerでインストールします。

composer require league/flysystem-aws-s3-v3 "^3.0"

ステップ②：.env に認証情報を設定

プロジェクト直下の .envファイル に、控えておいたAWSの認証情報とバケット設定を追記します。

# デフォルトのファイルシステムディスクをS3にする場合は変更（省略時はlocalやpublic）
FILESYSTEM_DISK=s3

# AWS S3設定
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_DEFAULT_REGION=ap-northeast-1
AWS_BUCKET=laravel-app-storage-sample
AWS_USE_PATH_STYLE_ENDPOINT=false

# CloudFront（CDN）やカスタムドメインを使用する場合（省略可）
# AWS_URL=https://d111111abcdef8.cloudfront.net

ステップ③：config/filesystems.php の設定確認・カスタマイズ

config/filesystems.php の disks 配列にある s3 設定を確認します。

'disks' => [

    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
        'throw' => false,
    ],

    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'url' => env('APP_URL').'/storage',
        'visibility' => 'public',
        'throw' => false,
    ],

    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION', 'ap-northeast-1'),
        'bucket' => env('AWS_BUCKET'),
        'url' => env('AWS_URL'),
        'endpoint' => env('AWS_ENDPOINT'),
        'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
        'throw' => true, // エラー発生時に例外をスロー（デバッグ・確実な検知のためtrue推奨）
        'visibility' => 'public', // アップロード時のデフォルト公開設定
    ],

],

ステップ④：設定キャッシュのクリア

.env を書き換えた後は、設定キャッシュを必ずクリアして最新の設定値を読み込ませます。

php artisan config:clear

※ .envが反映されない問題 の原因の多くは設定キャッシュの残存によるものです。

4. 【フロントエンド実装】Bladeテンプレートと画像アップロードフォーム

ユーザーが画像を選択してアップロードできるWebフォームを作成します。

ルーティングの定義（routes/web.php）

use App\Http\Controllers\ImageUploadController;
use Illuminate\Support\Facades\Route;

Route::get('/images/upload', [ImageUploadController::class, 'create'])->name('images.create');
Route::post('/images/upload', [ImageUploadController::class, 'store'])->name('images.store');

Bladeテンプレート（resources/views/images/create.blade.php）

ファイル送信には enctype="multipart/form-data" と @csrf ディレクティブが必須です。さらに、JavaScriptで選択した画像を即座にプレビュー表示するUX向上コードを含めています。

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>S3画像アップロード - Laravel Wren</title>
    <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-gray-50 text-gray-800 min-h-screen py-10">
    <div class="max-w-xl mx-auto bg-white p-8 rounded-xl shadow-md">
        <h1 class="text-2xl font-bold mb-6 text-gray-900">画像をS3にアップロード</h1>

        {{-- フラッシュメッセージ表示 --}}
        @if (session('success'))
            <div class="mb-6 p-4 bg-green-50 border border-green-200 text-green-700 rounded-lg">
                <p class="font-semibold">{{ session('success') }}</p>
                @if (session('image_url'))
                    <div class="mt-3">
                        <p class="text-xs text-gray-500 mb-1">S3公開URL:</p>
                        <a href="{{ session('image_url') }}" target="_blank" class="text-blue-600 underline text-sm break-all">
                            {{ session('image_url') }}
                        </a>
                        <div class="mt-3">
                            <img src="{{ session('image_url') }}" alt="Uploaded Image" class="max-h-48 rounded-lg shadow-sm border">
                        </div>
                    </div>
                @endif
            </div>
        @endif

        {{-- バリデーションエラー表示 --}}
        @if ($errors->any())
            <div class="mb-6 p-4 bg-red-50 border border-red-200 text-red-700 rounded-lg">
                <ul class="list-disc list-inside text-sm space-y-1">
                    @foreach ($errors->all() as $error)
                        <li>{{ $error }}</li>
                    @endforeach
                </ul>
            </div>
        @endif

        <form action="{{ route('images.store') }}" method="POST" enctype="multipart/form-data" class="space-y-6">
            @csrf

            <div>
                <label for="title" class="block text-sm font-medium text-gray-700 mb-1">画像タイトル</label>
                <input type="text" name="title" id="title" value="{{ old('title') }}" 
                       class="w-full px-4 py-2 border rounded-lg focus:ring-2 focus:ring-blue-500 focus:outline-none @error('title') border-red-500 @enderror" 
                       placeholder="例：プロフィール写真">
            </div>

            <div>
                <label for="image" class="block text-sm font-medium text-gray-700 mb-1">画像ファイル（JPEG / PNG / WebP、最大5MB）</label>
                <input type="file" name="image" id="image" accept="image/jpeg,image/png,image/webp,image/gif"
                       class="w-full px-3 py-2 border rounded-lg file:mr-4 file:py-2 file:px-4 file:rounded-md file:border-0 file:text-sm file:font-semibold file:bg-blue-50 file:text-blue-700 hover:file:bg-blue-100"
                       onchange="previewImage(event)">
                
                {{-- クライアント側画像プレビュー領域 --}}
                <div id="preview-container" class="mt-4 hidden">
                    <p class="text-xs text-gray-500 mb-1">選択中のプレビュー:</p>
                    <img id="preview-img" src="" alt="Preview" class="max-h-48 rounded-lg border shadow-sm">
                </div>
            </div>

            <button type="submit" class="w-full bg-blue-600 hover:bg-blue-700 text-white font-semibold py-3 px-4 rounded-lg transition duration-200 shadow-md">
                S3にアップロードする
            </button>
        </form>
    </div>

    <script>
        function previewImage(event) {
            const input = event.target;
            const container = document.getElementById('preview-container');
            const preview = document.getElementById('preview-img');
            
            if (input.files && input.files[0]) {
                const reader = new FileReader();
                reader.onload = function(e) {
                    preview.src = e.target.result;
                    container.classList.remove('hidden');
                }
                reader.readAsDataURL(input.files[0]);
            } else {
                container.classList.add('hidden');
            }
        }
    </script>
</body>
</html>

5. 【バリデーション】FormRequestによる安全な画像検証

画像アップロード機能では、悪意ある実行ファイル（PHPスクリプト等）のアップロードや巨大ファイルによるサーバーダウンを防ぐため、厳格なバリデーションが必須です。

Laravelの FormRequest を作成してロジックを分離します。

php artisan make:request UploadImageRequest

生成された app/Http/Requests/UploadImageRequest.php を以下のように記述します：

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class UploadImageRequest extends FormRequest
{
    /**
     * リクエストの実行権限を判定
     */
    public function authorize(): bool
    {
        return true; // 認証が必要な場合は auth()->check() 等を指定
    }

    /**
     * バリデーションルールの定義
     *
     * @return array
     */
    public function rules(): array
    {
        return [
            'title' => ['required', 'string', 'max:100'],
            'image' => [
                'required',
                'file',
                'image', // JPEG, PNG, BMP, GIF, SVG, WebP形式を自動判定
                'mimes:jpeg,png,jpg,webp,gif', // 許可する拡張子/MIMEタイプを厳密に制限
                'max:5120', // 最大ファイルサイズ 5MB（キロバイト単位: 5120KB）
                'dimensions:min_width=100,min_height=100,max_width=5000,max_height=5000', // 解像度制限
            ],
        ];
    }

    /**
     * カスタムエラーメッセージの定義
     */
    public function messages(): array
    {
        return [
            'title.required' => '画像のタイトルを入力してください。',
            'image.required' => '画像ファイルを選択してください。',
            'image.file' => 'アップロードされたファイルが無効です。',
            'image.image' => '画像ファイル（JPEG, PNG, WebP, GIF）を指定してください。',
            'image.mimes' => '画像形式は jpeg, png, jpg, webp, gif のいずれかを指定してください。',
            'image.max' => '画像サイズは5MB以内にしてください。',
            'image.dimensions' => '画像サイズは 100x100px 以上、5000x5000px 以内にしてください。',
        ];
    }
}

6. 【コントローラー実装】S3への画像アップロードと保存処理

次に、アップロードされた画像ファイルをS3に保存するコントローラーを作成します。

php artisan make:controller ImageUploadController

app/Http/Controllers/ImageUploadController.php の実装コードです：

<?php

namespace App\Http\Controllers;

use App\Http\Requests\UploadImageRequest;
use App\Models\UploadedImage;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Storage;
use Illuminate\View\View;

class ImageUploadController extends Controller
{
    /**
     * アップロードフォームを表示
     */
    public function create(): View
    {
        return view('images.create');
    }

    /**
     * S3へ画像をアップロードしてDBに保存
     */
    public function store(UploadImageRequest $request): RedirectResponse
    {
        // 1. アップロードされたファイルオブジェクトを取得
        $uploadedFile = $request->file('image');

        // 2. S3上の保存ディレクトリを指定（例: uploads/images/YYYY/MM）
        $directory = 'uploads/images/' . date('Y/m');

        try {
            // 3. Storageファサードの putFile メソッドでS3に保存（ランダムハッシュ名が自動生成される）
            // 第3引数で可視性 'public' を明示指定可能
            $path = Storage::disk('s3')->putFile($directory, $uploadedFile, 'public');

            if (!$path) {
                throw new \RuntimeException('S3へのファイル保存に失敗しました。');
            }

            // 4. S3上の公開URLを取得
            $url = Storage::disk('s3')->url($path);

            // 5. データベーストランザクションでメタデータを永続化
            DB::transaction(function () use ($request, $path, $url, $uploadedFile) {
                UploadedImage::create([
                    'title' => $request->input('title'),
                    'disk' => 's3',
                    'file_path' => $path,
                    'file_url' => $url,
                    'file_name' => $uploadedFile->getClientOriginalName(),
                    'mime_type' => $uploadedFile->getClientMimeType(),
                    'file_size' => $uploadedFile->getSize(),
                ]);
            });

            Log::info('Image successfully uploaded to S3', ['path' => $path, 'url' => $url]);

            return redirect()
                ->route('images.create')
                ->with('success', '画像が正常にS3へアップロードされました！')
                ->with('image_url', $url);

        } catch (\Throwable $e) {
            // 万が一DB保存に失敗した場合はS3上の孤立ファイルを削除するロールバック処理
            if (isset($path) && Storage::disk('s3')->exists($path)) {
                Storage::disk('s3')->delete($path);
            }

            Log::error('S3 Image Upload Failed: ' . $e->getMessage(), [
                'exception' => $e,
                'trace' => $e->getTraceAsString(),
            ]);

            return back()
                ->withInput()
                ->withErrors(['image' => 'アップロード中にエラーが発生しました: ' . $e->getMessage()]);
        }
    }
}

アップロード記法のバリエーション解説

Laravelでは状況に応じて複数の書き方が選べます：

7. 【画像の表示と取得】公開URL・署名付きURL・ファイル操作

S3に保存した画像は、利用用途（全体公開か、認証ユーザー限定か）に応じて適切な方法でURLを取得・表示します。

① 公開URLの取得（パブリック画像）

バケットが公開設定されている場合、Storage::disk('s3')->url($path) で完全なURLを取得できます。

$path = 'uploads/images/2026/08/sample.jpg';
$url = Storage::disk('s3')->url($path);
// 出力: https://laravel-app-storage-sample.s3.ap-northeast-1.amazonaws.com/uploads/images/2026/08/sample.jpg

Bladeテンプレートでの表示方法：

{{-- DBに保存したS3パスから表示 --}}
<img src="{{ Storage::disk('s3')->url($uploadedImage->file_path) }}" alt="{{ $uploadedImage->title }}" class="w-full h-auto rounded">

{{-- モデルのアクセサ（ゲッター）を活用する場合 --}}
<img src="{{ $uploadedImage->image_url }}" alt="Profile">

② 一時的署名付きURL（Temporary URL）の取得（非公開画像）

有料会員限定コンテンツ、請求書PDF、プライベートな機密画像など、S3バケットを非公開にしたまま、特定ユーザーに期間限定（例: 30分間）で閲覧権限を与えたい場合は temporaryUrl() を使用します。

use Illuminate\Support\Facades\Storage;

// 30分間だけ有効な認証トークン付きURLを生成
$temporaryUrl = Storage::disk('s3')->temporaryUrl(
    'private/documents/contract.pdf',
    now()->addMinutes(30)
);

// 出力例: https://laravel-app-storage-sample.s3.ap-northeast-1.amazonaws.com/private/documents/contract.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Expires=1800&X-Amz-Signature=...

③ その他の便利なファイル操作メソッド

// ファイルの存在確認
if (Storage::disk('s3')->exists($path)) {
    // 存在する場合の処理
}

// ファイルの削除
Storage::disk('s3')->delete($path);

// 複数ファイルの一括削除
Storage::disk('s3')->delete([$path1, $path2]);

// ファイルのダウンロードレスポンス（ブラウザでダウンロードダイアログを開かせる）
return Storage::disk('s3')->download($path, 'ユーザーに見せるファイル名.jpg');

// ファイルサイズの取得（バイト数）
$size = Storage::disk('s3')->size($path);

// 最終更新日時の取得（UNIXタイムスタンプ）
$lastModified = Storage::disk('s3')->lastModified($path);

8. 【実務応用】CloudFront CDN配信とローカル開発環境（MinIO）

CloudFront（CDN）連携による高速配信とコスト削減

実務で大量の画像トラフィックが発生する場合、S3から直接画像を配信するのではなく、前段に Amazon CloudFront（CDN） を配置するのが標準的なアーキテクチャです。

CloudFrontを導入すると、世界中のエッジサーバーに画像がキャッシュされ、レスポンス速度が高速化されるとともに、AWSのデータ転送アウト料金を大幅に削減できます。

CloudFront導入時の .env 設定：

AWS_URL=https://d123456abcdef8.cloudfront.net
# または独自ドメインを設定している場合
# AWS_URL=https://images.example.com

.env に AWS_URL を指定すると、Storage::disk('s3')->url($path) は自動的にCloudFrontのドメインを付与したURL（https://d123456abcdef8.cloudfront.net/uploads/images/...）を返すようになります。

ローカル環境（MinIO / Laravel Sail）でのS3エミュレーション

Laravel Sail環境 やDockerローカル環境で本物のAWSアカウントを使わずにS3のテストを行いたい場合は、オープンソースのS3完全互換ストレージ MinIO を利用できます。

docker-compose.yml のMinIO定義：

minio:
  image: 'minio/minio:latest'
  ports:
    - '${FORWARD_MINIO_PORT:-9000}:9000' # S3 APIポート
    - '${FORWARD_MINIO_CONSOLE_PORT:-8900}:8900' # Webコンソール
  environment:
    MINIO_ROOT_USER: 'sail'
    MINIO_ROOT_PASSWORD: 'password'
  command: 'minio server /data --console-address ":8900"'
  volumes:
    - 'sail-minio:/data'
  networks:
    - sail

MinIO利用時のローカル .env 設定：

AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local-bucket
AWS_ENDPOINT=http://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

9. よくあるエラー・トラブルシューティング

S3連携で開発者がつまずきやすいエラーとその解決策をまとめました。

① Aws\S3\Exception\S3Exception: Access Denied (403 Forbidden)

② Class "League\Flysystem\AwsS3V3\AwsS3V3Adapter" not found

③ アップロードは成功するが画像URLにアクセスすると 403 Forbidden になる

④ .env を変更したのに古いバケット名やキーが参照される

⑤ 413 Request Entity Too Large / ファイルサイズ超過エラー

10. まとめ＆S3画像アップロード実装チェックリスト

LaravelのStorageファサードとFlysystemを活用することで、クラウドストレージAmazon S3との連携は非常にシンプルかつセキュアに構築できます。

ぜひ本記事を参考に、スケーラブルで安全な画像・ファイル管理基盤をLaravelアプリケーションに構築してみてください！