Kamu mengunggah foto produk lewat form, datanya tersimpan, tetapi di halaman gambarnya rusak atau tampil ikon patah. Masalah gambar upload yang tidak muncul di Laravel termasuk yang paling sering ditanyakan, dan penyebabnya hampir selalu berkaitan dengan cara Laravel memisahkan penyimpanan berkas dari folder publik. Artikel ini menguraikan cara kerjanya, lalu menelusuri penyebab satu per satu: storage:link, izin folder, APP_URL, konfigurasi disk, dan web server.
Cara Laravel menyimpan berkas unggahan
Berkas unggahan sebaiknya tidak ditaruh langsung di folder public, karena folder itu ikut terkirim bersama kode dan sulit dikelola. Laravel menyimpannya di storage/app/public. Folder ini tidak bisa diakses langsung dari web, sehingga Laravel menyediakan tautan simbolik dari public/storage ke storage/app/public. Dengan tautan itu, berkas di dalam storage seolah-olah ada di folder publik.
Kode penyimpanan yang umum terlihat seperti ini:
$path = $request->file('foto')->store('produk', 'public');
// $path berisi: produk/abc123.jpg
$produk->update(['foto' => $path]);Dan di tampilan, URL dibangun dari jalur tersebut:
<img src="{{ asset('storage/' . $produk->foto) }}" alt="{{ $produk->nama }}">Jika salah satu mata rantai putus, gambar tidak tampil. Mari kita periksa satu per satu.
Penyebab 1: tautan storage belum dibuat
Ini penyebab nomor satu, terutama setelah memindahkan proyek ke komputer atau server baru. Tautan simbolik tidak ikut terbawa saat kode disalin atau di-clone dari Git, jadi harus dibuat ulang.
php artisan storage:linkPerintah itu membuat public/storage yang menunjuk ke storage/app/public. Cek hasilnya:
ls -l public/ | grep storageBila sudah benar, tampak panah seperti storage -> /var/www/app/storage/app/public. Bila folder public/storage ada tetapi merupakan folder biasa, bukan tautan, hapus dulu lalu jalankan ulang perintahnya. Bila muncul pesan bahwa tautan sudah ada namun rusak, hapus berkas itu dengan rm public/storage lalu buat ulang.
Penyebab 2: izin folder tidak cukup
Laravel perlu menulis ke storage, dan web server perlu membaca berkas di dalamnya. Bila izin salah, unggahan gagal diam-diam atau gambar tidak bisa dibaca.
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cacheNama www-data berlaku di Ubuntu dengan Nginx atau Apache. Di hosting cPanel, pastikan izin folder 755 dan berkas 644 melalui manajer berkas. Hindari chmod 777 walaupun terasa menyelesaikan masalah, karena membuka akses tulis bagi semua pengguna di server.
Penyebab 3: APP_URL salah
URL dari asset() dan Storage::url() dibentuk dari APP_URL di berkas .env. Jika nilainya masih http://localhost padahal situs berjalan di domain asli, gambar mengarah ke alamat yang salah.
APP_URL=https://contoh.comSetelah mengubahnya, bersihkan cache konfigurasi:
php artisan config:clearPerhatikan juga skema. Bila situsmu memakai HTTPS tetapi APP_URL memakai http, peramban bisa memblokir gambar sebagai konten campuran, dan di konsol peramban muncul peringatan tentang mixed content.
Penyebab 4: disk tidak sesuai
Laravel punya beberapa disk di config/filesystems.php. Disk local menyimpan di storage/app/private pada versi baru, sedangkan disk public menyimpan di storage/app/public. Bila kamu menyimpan ke disk local tetapi menampilkan lewat jalur publik, berkasnya tidak akan ditemukan.
// Menyimpan ke disk publik
$request->file('foto')->store('produk', 'public');
// Mengambil URL dari disk yang sama
Storage::disk('public')->url($produk->foto);Pastikan disk yang dipakai saat menyimpan sama dengan disk yang dipakai saat membangun URL. Pada config/filesystems.php, disk public seharusnya punya root ke storage_path('app/public') dan url ke env('APP_URL').'/storage'.
Penyebab 5: hosting bersama tanpa symlink
Sebagian hosting bersama menonaktifkan fungsi symlink atau tidak menyediakan akses SSH, sehingga storage:link tidak bisa dijalankan. Ada dua jalan keluar yang aman.
Pertama, buat tautan lewat rute sementara yang dijalankan sekali, lalu hapus rutenya:
Route::get('/buat-link', function () {
symlink(storage_path('app/public'), public_path('storage'));
return 'Tautan dibuat';
});Kedua, bila fungsi symlink diblokir, ubah disk publik agar menyimpan langsung di folder publik:
'public' => [
'driver' => 'local',
'root' => public_path('uploads'),
'url' => env('APP_URL').'/uploads',
'visibility' => 'public',
],Dengan cara kedua, tidak perlu tautan, tetapi berkas unggahan ikut berada di folder publik. Pastikan hanya jenis berkas yang aman, seperti gambar, yang boleh diunggah, dan jangan pernah mengizinkan unggahan berkas PHP.
Penyebab 6: konfigurasi Nginx menghalangi
Bila tautan benar tetapi gambar tetap 404 atau 403, periksa konfigurasi web server. Pada Nginx, pastikan document root mengarah ke folder public dan tidak ada aturan yang memblokir folder storage. Pastikan juga opsi mengikuti tautan simbolik tidak dimatikan. Aturan blokir berkas tersembunyi yang terlalu luas kadang ikut menolak jalur tertentu.
root /var/www/aplikasi/public;
location / {
try_files $uri $uri/ /index.php?$query_string;
}Uji langsung lewat peramban atau curl:
curl -I https://contoh.com/storage/produk/abc123.jpgKode 200 berarti berkas terbaca. Kode 404 berarti tautan atau jalur salah. Kode 403 berarti masalah izin atau aturan web server.
Penyebab 7: jalur tersimpan salah di database
Kadang berkas ada, tetapi jalur di database tidak sesuai, misalnya tersimpan dengan awalan public/ atau dengan jalur absolut. Periksa isi kolom dan bandingkan dengan lokasi berkas sebenarnya:
ls storage/app/public/produk | headBila database menyimpan public/produk/abc123.jpg padahal berkas ada di produk/abc123.jpg, URL yang dibangun akan salah. Simpan jalur relatif terhadap disk, persis seperti yang dikembalikan store().
Daftar periksa
- Jalankan
php artisan storage:linkdan pastikanpublic/storageberupa tautan. - Pastikan izin
storagebenar dan dapat dibaca web server. - Samakan
APP_URLdengan domain dan skema yang dipakai. - Pastikan disk penyimpanan sama dengan disk untuk URL.
- Uji alamat gambar langsung dengan
curl -I. - Periksa jalur yang tersimpan di database.
Bila masih belum muncul
Bila semua sudah dicek dan gambar tetap hilang, kumpulkan bahan: alamat gambar yang gagal, kode status dari curl, isi bagian disk di konfigurasi, dan lingkunganmu. Untuk bantuan langsung, ada jasa Laravel yang mengerjakan fitur unggah berkas lengkap, jasa deploy Laravel ke VPS untuk urusan server, dan jasa debugging dan perbaikan error. Siap melanjutkan? Ajukan pesanan dan kita tulis ruang lingkupnya di SOW.