Laravel storage link, storage/app/public içinde tutulan herkese açık dosyaları public/storage adresinden sunmak için oluşturulan sembolik bağlantıdır. Komut başarılı görünmesine rağmen yüklenen görseller 404 verebilir, bağlantı yanlış dizini gösterebilir veya hosting sağlayıcısı symlink oluşturulmasını engelleyebilir.
Bu rehberde yalnızca php artisan storage:link komutunu çalıştırmayacağız. Public disk ayarını, gerçek dosya konumunu, oluşturulan bağlantının hedefini, URL üretimini ve web sunucusunun erişimini ayrı ayrı doğrulayacağız. Böylece sorun komutta mı, dosya sisteminde mi yoksa uygulama kodunda mı netleşecek.
Laravel storage link nasıl çalışır?
Laravel’in resmî dosya sistemi dokümantasyonuna göre varsayılan public diski dosyaları storage/app/public altında saklar. php artisan storage:link komutu, bu klasöre işaret eden public/storage bağlantısını oluşturur. Tarayıcıdan erişilen /storage/dosya.jpg adresi böylece gerçek dosyaya ulaşır.
storage/app/public <-- gerçek dosyalar
public/storage <-- sembolik bağlantı
/storage/file.jpg <-- tarayıcıdan erişilen URLBu yapı yalnızca herkese açık dosyalar içindir. Kimlik belgesi, özel fatura, kullanıcıya özel rapor veya erişim kontrolü gerektiren dosyaları public diske koymayın. Bu tür içerikleri private diskte tutup yetkilendirilmiş controller yanıtı ya da süreli URL ile sunun.
Storage link kurulumundan önce diski doğrulayın
Önce config/filesystems.php içindeki public diskini kontrol edin. Varsayılan yapıda kök dizin storage_path('app/public'), URL ise env('APP_URL').'/storage' olur. APP_URL yanlışsa dosya doğru yerde olsa bile üretilen adres farklı domaine veya HTTP protokolüne gidebilir.
'public' => [
'driver' => 'local',
'root' => storage_path('app/public'),
'url' => env('APP_URL').'/storage',
'visibility' => 'public',
'throw' => false,
],Yapılandırma değişikliğinden sonra eski değer kullanılıyorsa Laravel config cache hatası rehberindeki doğrulama sırasını uygulayın. Önce config değerini görün, ardından gerekli cache’i kontrollü biçimde yeniden oluşturun.
Adım adım storage link oluşturma
Komutu Laravel projesinin, yani artisan dosyasının bulunduğu kök dizinde çalıştırın:
php artisan storage:linkArdından bağlantının varlığını ve hedefini sunucuda kontrol edin:
ls -la public/storage
ls -la storage/app/publicTest dosyasını uygulama üzerinden public diske yazmak, hem disk ayarını hem izinleri doğrular. Canlı projede rastgele dosya oluşturmadan önce bunun etkisini değerlendirin ve test sonrasında dosyayı kaldırın.
use Illuminate\Support\Facades\Storage;
Storage::disk('public')->put('health/storage-link.txt', 'ok');
$url = Storage::disk('public')->url('health/storage-link.txt');Tarayıcıda üretilen URL’yi açın. Dosya diskte yoksa upload veya disk seçimi; dosya var ama URL 404 ise symlink, document root ya da web sunucusu erişimi üzerinde yoğunlaşın. Dosya yükleme verisini controller’a gelmeden önce doğrulamak için Laravel Validation rehberini kullanabilirsiniz.
Yaygın storage link hataları ve çözümleri
The link already exists hatası
Bu mesaj, public/storage yolunda zaten bir dosya, klasör veya bağlantı bulunduğunu gösterir. Mevcut hedefi doğrulamadan silmeyin. Güncel Laravel sürümlerinde yapılandırılmış bağlantıları kaldırmak için php artisan storage:unlink kullanılabilir; ardından storage:link ile yeniden oluşturabilirsiniz. Bağlantı dışındaki gerçek bir klasör varsa önce içeriğini yedekleyip neden oluşturulduğunu araştırın.
Dosya var ama 404 dönüyor
Document root’un Laravel’in public klasörünü gösterdiğini kontrol edin. Proje kökünü web’e açmak yalnızca storage bağlantısını bozmakla kalmaz, hassas yapılandırma dosyalarını da riske atar. Shared hosting dizin yerleşimi farklıysa Laravel shared hosting kurulum rehberindeki public klasör yaklaşımını izleyin.
Permission denied hatası
Resmî Laravel deployment dokümantasyonu, web sunucusu sürecinin storage ve bootstrap/cache dizinlerine yazabilmesini ister. Sorunu chmod -R 777 ile kapatmayın. Dosya sahibi, web sunucusu grubu ve gerekli en dar izinleri hosting yapınıza göre düzenleyin. Daha geniş kontroller için Laravel güvenlik kontrol listesini inceleyin.
APP_URL veya HTTPS uyuşmazlığı
Storage::url() yanlış protokol ya da domain üretiyorsa APP_URL, proxy başlıkları ve public disk URL ayarını kontrol edin. Değişiklikten sonra config cache’i yeniden oluşturun. Elle URL birleştirmek yerine disk API’sini kullanmak, ileride S3 gibi başka bir sürücüye geçişi de kolaylaştırır.
Shared hosting symlink izni vermiyorsa ne yapılır?
Bazı paylaşımlı hosting paketleri güvenlik politikası nedeniyle sembolik bağlantıyı engeller. Önce sağlayıcıdan terminalde symlink desteğinin ve doğru PHP komutunun doğrulanmasını isteyin. Linki her deployment’ta dosya kopyalayarak taklit etmek, eski ve çift dosya üretir; kalıcı çözüm olarak önerilmez.
Sağlayıcı symlink’i kesin olarak desteklemiyorsa proje gereksinimine göre public disk kökünü kontrollü bir web dizinine taşımak veya S3 uyumlu nesne depolama kullanmak değerlendirilebilir. Public dizine taşınan her dosyanın internete açık olacağını unutmayın. Hassas dosyalar için private disk ve uygulama seviyesinde yetkilendirme kullanın.
Deployment ve güvenlik kontrol listesi
- Document root yalnızca Laravel
publicklasörünü göstersin. public/storagebağlantısının hedefi yeni release yapısında doğru dizin olsun.- Upload doğrulamasında MIME türü, boyut ve yetki kuralları uygulansın.
- Özel dosyalar public diske kaydedilmesin.
- Deployment sonrasında örnek dosya URL’si veya health check ile erişim doğrulansın.
- Otomatik yayın akışı için GitHub Actions deployment rehberindeki geri dönüş ve doğrulama adımları uyarlansın.
Sonuç
Laravel storage link sorunu; gerçek dosya konumu, sembolik bağlantı hedefi, public disk URL’si ve web sunucusu document root’u birlikte doğrulandığında çözülebilir. Komutun başarı mesajına tek başına güvenmek yerine uygulama üzerinden dosya yazıp üretilen URL’yi test edin. Hosting symlink’i engelliyorsa güvenliği zayıflatan izinler vermeden sağlayıcı desteği, kontrollü disk yapılandırması veya nesne depolama seçeneğine geçin.
Sık sorulan sorular
Laravel storage link komutu nedir?
Varsayılan public disk için komut php artisan storage:link şeklindedir. Bu işlem public/storage bağlantısını storage/app/public hedefine yönlendirir.
Storage link nasıl kaldırılır?
Yapılandırılmış sembolik bağlantıları kaldırmak için güncel Laravel sürümlerinde php artisan storage:unlink kullanılabilir. Mevcut yol gerçek klasörse komutu veya manuel silme işlemini uygulamadan önce içeriği kontrol edin.
Yüklenen görseller neden 404 veriyor?
Dosya yanlış diske kaydedilmiş, symlink yanlış hedefi gösteriyor, document root hatalı veya URL ayarı eski olabilir. Önce dosyanın storage/app/public altında bulunduğunu ve public/storage bağlantısının doğru hedefe gittiğini doğrulayın.
Storage klasörüne 777 izni verilmeli mi?
Hayır. Herkese yazma izni vermek güvenlik riskidir. Web sunucusu kullanıcısı veya grubuna, yalnızca uygulamanın ihtiyaç duyduğu dizinlerde en dar yazma iznini sağlayın.
Private dosyalar storage link ile sunulur mu?
Sunulmamalıdır. Storage link public disk içeriğini doğrudan web erişimine açar. Özel dosyaları private diskte tutup kullanıcı yetkisini kontrol eden bir indirme yanıtı veya süreli URL kullanın.
