storage:link — 公開ディスクとstorageフォルダをリンクするコマンド

php artisan storage:link は public/storage というシンボリックリンクを作成し、storage/app/public に格納されたファイルを Web からアクセス可能にします。
開発・本番で同じコマンドを実行できるので、アップロード機能をすぐに動かせます。
※ Windows では管理者権限が必要です。

概要

• カテゴリ: artisan
• Laravel 版: 12
• PHP 版: 8.4
• 関連項目: public_disk, filesystem, public_folder, storage_path
• 変更履歴
• 5.0.0 で導入
• 8.0 で --force オプションが追加

storage:link は config/filesystems.php の public ディスクと連携し、ファイルアップロードやダウンロードの際に使われます。

シグネチャ

php artisan storage:link [--force]

引数（表）

引数	型	必須	既定値	説明
--force	bool	0	false	既に public/storage が存在している場合に上書きする

戻り値

型	意味
void	コマンドは標準出力に結果を出力し、終了コードで成功/失敗を示す

例外 / 副作用

種類	内容	発生条件	対応
エラー	The storage link already exists.	リンクが既存で --force 未指定	--force で上書き
エラー	Symlink failed.	パーミッション不足・Windows権限	適切な権限を付与、管理者権限で実行
エラー	Command not found	Artisan がインストールされていない	composer install で再インストール

最小例

php artisan storage:link

実務例

# 既存リンクを上書きして作成
php artisan storage:link --force

# デプロイスクリプト内で実行
./vendor/bin/sail artisan storage:link

実行環境

• PHP の symlink() が有効である必要があります。
• Linux / macOS: 権限が許せばそのまま実行。
• Windows: シンボリックリンクを作るには管理者権限が必要。icacls で権限付与、あるいは mklink /D を手動で実行。
• CI 環境では --force を付けることで既存リンクの上書きが保証されます。

副作用

• public/storage にシンボリックリンクを作成するので、ファイルパスが変わる。
• 既存のリンクやディレクトリがある場合は上書きされます（--force で必ず上書き）。
• シンボリックリンクが作れないとファイル公開ができません。

終了コード

コード	意味
0	成功
1	失敗（エラー）

スケジューラ例

// app/Console/Kernel.php

protected function schedule(Schedule $schedule): void
{
    $schedule->command('storage:link')
             ->dailyAt('02:00')
             ->withoutOverlapping()
             ->runInBackground();
}

代替手段・比較

手段	メリット	デメリット	推奨ケース
php artisan storage:link	Laravel 標準、設定が一元管理	Windows で制限	一般的に推奨
ln -s / mklink	OS レベルで柔軟	手動で管理	スクリプト化が必要
Cloud Storage 直接公開	スケーラブル	追加設定が必要	大規模サービス

テスト例（Pest）

it('creates a storage link', function () {
    $this->artisan('storage:link')
         ->expectsOutput('The storage link has been successfully created.')
         ->assertExitCode(0);

    expect(public_path('storage'))->toBeDirectory();
});

トラブルシュート

症状	原因	対処
The storage link already exists.	既存リンクがある	--force オプションで上書き
Symlink failed.	パーミッション不足 / Windows権限	必要権限を付与、管理者権限で実行
Command not found	Artisan 未インストール	composer install を実行

参考リンク（リンク名のみ）

• Laravel 公式ドキュメント: Storage
• PHP Manual: symlink()
• Unix/Linux ln コマンドリファレンス

---