روی local همه چیز درسته. آپلود میکنی، تصویر باز میشه، آواتار میاد. ولی همون پروژه رو که میبری روی سرور با Nginx، URLهایی مثل /storage/avatars/user1.jpg میشن ۴۰۴. بعضی وقتا هم فقط بعد از یه deploy تازهست که میشکنه، در حالی که release قبلی هنوز درست کار میکرد.
اگه لینک storage لاراول 404 میده، معمولاً پای یکی از اینهاست: symlink ساخته نشده، Nginx با disable_symlinks جلوش رو گرفته، permission یا owner اشتباهه، document root به public/ اشاره نمیکنه، روی shared hosting گیر کردی، یا zero-downtime deploy لینک رو به shared storage وصل نکرده. توی این مقاله هر کدوم رو با دستور تشخیص و رفع میریم جلو، تفاوت Storage::url و asset رو هم میبینیم، و یه الگوی deploy میذاریم که دیگه این داستان تکرار نشه.
جواب کوتاه برای کسی که عجله داره
از root پروژه (نه از داخل public/):
mkdir -p storage/app/public
php artisan storage:link --force
ls -la public/ | grep storage
# باید چیزی شبیه این ببینی:
# lrwxrwxrwx ... storage -> ../storage/app/public
بعد Nginx رو چک کن:
sudo nginx -T 2>/dev/null | grep disable_symlinks
# نباید disable_symlinks on باشه
sudo nginx -T 2>/dev/null | grep -E '^\s*root\s+'
# باید به .../public برسه، نه به root پروژه
اگه symlink درسته و باز هم ۴۰۴ میگیری، برو سراغ جدول تشخیص پایینتر. بقیهی مقاله جزئیات هر سناریو رو باز میکنه.
public/storage اصلاً چیه؟
طبق مستندات فایلسیستم لاراول، فایلهایی که میخوای از وب دیده بشن باید توی storage/app/public باشن، و یه symbolic link از public/storage به همون مسیر ساخته بشه:
/var/www/your-app/
├── storage/
│ └── app/
│ └── public/ ← فایل واقعی اینجاست
│ ├── avatars/
│ │ └── user1.jpg
│ └── uploads/
└── public/ ← document root مربوط به Nginx
├── index.php
└── storage -> ../storage/app/public ← symlink
وقتی کاربر https://example.com/storage/avatars/user1.jpg رو باز میکنه، Nginx میره سراغ public/storage/... و چون storage یه symlinkه، فایل واقعی پیدا میشه. اگه symlink نباشه، یا Nginx نتونه دنبالش بره، ۴۰۴ میگیری.
دستور php artisan storage:link آرایهی links توی config/filesystems.php رو میخونه:
'links' => [
public_path('storage') => storage_path('app/public'),
],
اگه لازم داری لینکهای بیشتری داشته باشی، همونجا اضافه کن:
'links' => [
public_path('storage') => storage_path('app/public'),
public_path('images') => storage_path('app/images'),
],
تشخیص سریع: کدوم سناریو رو داری؟
قبل از اینکه پشت سر هم دستور clear بزنی، با این جدول بفهم مشکل از کجاست:
| سناریو | علامت | دستور تشخیص | نتیجهی درست | نتیجهی شکست |
|---|---|---|---|---|
| ۱. symlink نیست | /storage/... ۴۰۴ |
ls -la public/ | grep storage |
storage -> ../storage/app/public |
drwxr-xr-x ... storage (دایرکتوری واقعی) |
۲. disable_symlinks on |
۴۰۴ + لاگ symlink not allowed |
sudo nginx -T 2>/dev/null | grep disable_symlinks |
off یا اصلاً نباشه |
disable_symlinks on |
| ۳. permission/owner | ۴۰۴ + لاگ permission denied |
stat -c "%U:%G %a" storage/app/public |
مثلاً www-data:www-data 755 |
root:root 700 |
| ۴. document root اشتباه | /storage/... ۴۰۴ ولی / کار میکنه |
grep root /etc/nginx/sites-enabled/* |
root .../public; |
root .../your-app; بدون /public |
| ۵. shared hosting | symlink نیست، فقط File Manager | بدون SSH | symlink دستی یا cron | نمیتونی لینک بزنی |
| ۶. zero-downtime deploy | release جدید ۴۰۴، قبلی OK | ls -la releases/ && readlink current |
public/storage به shared اشاره کنه |
هر release لینک جدا داره |
| ۷. Docker دو کانتینر | حتی با symlink درست، ۴۰۴ | docker inspect روی app و nginx |
volume storage روی هر دو mount |
فقط روی app هست |
سناریوی ۱: symlink اصلاً ساخته نشده (رایجترین)
تشخیص
ls -la /var/www/your-app/public/ | grep storage
اگه خروجی شبیه drwxr-xr-x ... storage باشه، یعنی یه دایرکتوری واقعی اونجاست، نه symlink. باید این شکلی باشه:
lrwxrwxrwx 1 www-data www-data 23 Nov 3 12:00 storage -> ../storage/app/public
رفع
cd /var/www/your-app
mkdir -p storage/app/public
php artisan storage:link
اگه قبلاً چیزی به اسم storage توی public/ بوده و دستور File already exists میده:
# اگه داخلش چیزی مهم نیست:
rm -rf public/storage
php artisan storage:link
# یا بدون پاک کردن دستی:
php artisan storage:link --force
توی Laravel جدیدتر میتونی --relative هم بزنی تا لینک نسبی ساخته بشه. برای entrypoint کانتینر هم همین الگو خوبه:
mkdir -p storage/app/public
php artisan storage:link --force || echo "storage:link failed"
بعد از ساختن، محتوا رو تأیید کن:
ls -la public/storage/
# باید محتوای storage/app/public رو ببینی
یه نکته برای deployهای zero-downtime: storage:link رو کورکورانه توی هر release نزن اگه مسیر shared جدا داری. لینک باید به shared اشاره کنه، نه به storage داخل همون release. جزئیاتش توی سناریوی ۶ هست.
سناریوی ۲: symlink هست، ولی Nginx جلوش رو گرفته
طبق مستندات Nginx برای disable_symlinks، اگه این گزینه on باشه و هر بخشی از مسیر یه symbolic link باشه، دسترسی رد میشه.
sudo nginx -T 2>/dev/null | grep disable_symlinks
اگه disable_symlinks on دیدی:
server {
# ...
disable_symlinks off;
}
بعد:
sudo nginx -t
sudo systemctl reload nginx
پیشفرض Nginx معمولاً off هست، ولی بعضی توزیعها یا تمپلیتهای امنیتی اون رو on میذارن.
از نظر امنیتی، خاموش کردنش یعنی یه لایهی دفاعی در برابر symlink attack کمتر میشه. پس مطمئن شو root فقط به پوشهی public/ پروژهت اشاره میکنه، و اپلیکیشن اجازه نمیده کاربر بیرون از storage/app/public آپلود کنه یا symlink بسازه.
سناریوی ۳: permission یا owner اشتباه
ls -la storage/app/public/
stat -c "%U:%G %a" storage/app/public/
اگه owner برابر root:root باشه و worker مربوط به Nginx یا PHP-FPM با www-data اجرا بشه، فایل خونده نمیشه. حالتهای رایج:
root:root 700: worker وارد دایرکتوری نمیشه- owner درست، ولی mode فایل
600: بقیه نمیتونن بخونن - owner
forge:forgeو workerwww-data: mismatch گروهی
رفع معمول روی Debian یا Ubuntu:
sudo chown -R www-data:www-data /var/www/your-app/storage/app/public
sudo find /var/www/your-app/storage/app/public -type d -exec chmod 755 {} \;
sudo find /var/www/your-app/storage/app/public -type f -exec chmod 644 {} \;
(اسم کاربر روی بعضی پنلها www هست، نه www-data. همون کاربری رو بذار که PHP-FPM باهاش اجرا میشه.)
اگه SELinux فعاله (CentOS، RHEL، AlmaLinux):
getenforce
# Enforcing
sudo chcon -R -t httpd_sys_rw_content_t /var/www/your-app/storage/app/public
# یا:
sudo setsebool -P httpd_read_user_content 1
بدون context درست، حتی با chmod درست هم ممکنه درخواست بلاک بشه.
برای تست با همون کاربر وبسرور:
sudo -u www-data cat /var/www/your-app/storage/app/public/avatars/user1.jpg | head -c 10
# باید چند بایت اول فایل رو ببینی (مثلاً magic bytes مربوط به JPEG یا PNG)
سناریوی ۴: document root اشتباهه
sudo nginx -T 2>/dev/null | grep -E '^\s*root\s+'
# یا
grep root /etc/nginx/sites-enabled/*
باید این شکلی باشه:
root /var/www/your-app/public;
نه این:
# اشتباه: root پروژه، بدون /public
root /var/www/your-app;
اگه root روی پوشهی پروژه باشه، Nginx مسیر /storage رو جای دیگهای دنبال میکنه و ۴۰۴ میگیری، در حالی که صفحهی اصلی ممکنه هنوز بهخاطر rewrite یا تنظیم دیگه کار کنه. بعد از اصلاح:
sudo nginx -t
sudo systemctl reload nginx
سناریوی ۵: shared hosting (cPanel / Plesk)
روی shared hosting معمولاً SSH محدودی داری، public_html document root ثابته، و php artisan storage:link یا اصلاً در دسترس نیست یا PHP CLI مسیر عجیبی داره.
راه ۱: symlink دستی یا cron
توی File Manager مربوط به cPanel برو داخل public_html، اگه پوشهی storage هست و دایرکتوری معمولیه پاکش کن (یا عوض اسمش بده)، بعد یه symlink بساز به ../storage/app/public (یعنی یک سطح بالاتر از public_html، جایی که معمولاً storage پروژهت هست).
یا از cron:
cd /home/USER/your-app && /usr/local/bin/php artisan storage:link
مسیر PHP CLI رو از پشتیبانی هاست بپرس؛ چیزهایی مثل /usr/local/bin/php یا /opt/cpanel/ea-php83/root/usr/bin/php رایجه.
راه ۲: serve کردن از خود لاراول (آخرین تیر)
// routes/web.php
Route::get('/storage/{path}', function (string $path) {
abort_unless(
Storage::disk('public')->exists($path),
404
);
return Storage::disk('public')->response($path);
})->where('path', '.*');
این مسیر از PHP رد میشه، کندتره، middleware میخوره، و اگه درست محدودش نکنی ریسک امنیتی داره. پیشنهاد جدی: تا جایی که میشه symlink بزن. لاراول برای shared hosting طراحی نشده؛ اگه هاست اجازهی symlink نمیده، یا با پشتیبانی حرف بزن یا به VPS مهاجرت کن.
سناریوی ۶: zero-downtime deploy و symlink خراب
توی Capistrano، Deployer، Envoyer و الگوهای مشابه معمولاً چنین ساختاری داری:
/var/www/your-app/
├── current -> releases/20261103120000
├── releases/
│ ├── 20261102100000/
│ └── 20261103120000/
└── shared/
└── storage/
└── app/
└── public/
اگه توی هر release این کار رو بکنی:
# اشتباه: لینک نسبی داخل همون release
ln -s ../../../storage/app/public "$RELEASE/public/storage"
آپلودهای جدید یا میرن جای اشتباه، یا بعد از سوییچ current، release جدید فایلهای قبلی رو نمیبینه.
الگوی درست اینه که public/storage همیشه به shared اشاره کنه:
SHARED_DIR=/var/www/your-app/shared
RELEASE_DIR=/var/www/your-app/releases/20261103120000
mkdir -p "$SHARED_DIR/storage/app/public"
ln -sfn "$SHARED_DIR/storage/app/public" "$RELEASE_DIR/public/storage"
ln -sfn "$SHARED_DIR/.env" "$RELEASE_DIR/.env"
توی یه تسک سادهی Envoy تقریباً همین منطق رو میذاری: shared رو بساز، بعد ln -sfn به public/storage داخل release. این جوری آپلودها بین همهی releaseها مشترک میمونن.
اگه اسکریپت deployت رو با GitHub Actions میسازی، توی راهنمای deploy خودکار لاراول با GitHub Actions قدمبهقدم ساختیمش. حواست باشه بعد از سوییچ release، config:cache و بقیهی کشها رو هم درست بزنی؛ اگه با تغییرات .env گیر میکنی، راهنمای تغییرات env و config:cache رو ببین.
سناریوی ۷: Nginx و app توی دو کانتینر جدا
توی استکهای Docker یا Kubernetes معمولاً یک کانتینر PHP-FPM داری و یک کانتینر Nginx جدا. symlink توی کانتینر app ممکنه درست باشه، ولی اگه volume مربوط به storage روی کانتینر Nginx mount نشده باشه، Nginx به target نمیرسه و ۴۰۴ میده.
تشخیص:
docker inspect <app_container> --format '{{json .Mounts}}'
docker inspect <nginx_container> --format '{{json .Mounts}}'
رفع ساده با docker-compose:
services:
app:
volumes:
- app-storage:/var/www/html/storage
- ./public:/var/www/html/public
nginx:
volumes:
- app-storage:/var/www/html/storage:ro
- ./public:/var/www/html/public:ro
volumes:
app-storage:
نکته: همون volume باید روی هر دو باشه. روی Nginx بهتره read-only (:ro) باشه. توی Kubernetes هم همین ایده با یک PVC مشترک تکرار میشه: app نوشتنی، Nginx فقط خواندنی.
و باز هم: root مربوط به Nginx باید فقط public/ باشه. اگه آپلود کاربر بتونه symlink به مسیرهای سیستم بسازه، با disable_symlinks off ریسک واقعی داری.
Storage::url، asset و APP_URL
یکی از جاهایی که فکر میکنی symlink خرابه، ولی در واقع URL اشتباه ساخته میشه:
| روش | خروجی تقریبی | کی استفاده کنی | تلهی رایج |
|---|---|---|---|
asset('storage/avatars/user1.jpg') |
https://example.com/storage/... |
توی Blade | اگه APP_URL غلط باشه، دامنه اشتباه میشه |
Storage::disk('public')->url('avatars/user1.jpg') |
همون شکل | توی controller یا job | disk مربوط به public باید درست تعریف شده باشه |
Storage::url('...') |
بستگی به default disk داره | فقط وقتی default همون public باشه |
عوض کردن default همهچیز رو میشکنه |
| URL دستی hard-coded | رشتهی ثابت | هیچوقت | عوض شدن دامنه یعنی پیدا کردن همهی رشتهها |
توی config/filesystems.php برای disk مربوط به public معمولاً این رو میبینی:
'public' => [
'driver' => 'local',
'root' => storage_path('app/public'),
'url' => env('APP_URL').'/storage',
'visibility' => 'public',
],
پس APP_URL باید دقیقاً همون دامنهای باشه که کاربر سایت رو باهاش باز میکنه. اگه سایت روی www باشه و APP_URL بدون www، یا برعکس، ممکنه به ۴۰۴ یا redirect عجیب برسی. و یادت باشه بعد از عوض کردن .env باید کش config رو از نو بسازی.
اگه بعد از deploy فرانتاند هم به هم میریزه، ممکنه پای Vite باشه؛ راهنمای Vite manifest not found در لاراول رو کنار این مقاله نگه دار.
یه اسکریپت deploy که symlink رو نشکنه
#!/usr/bin/env bash
set -euo pipefail
REPO_DIR="/var/www/your-app"
SHARED_DIR="$REPO_DIR/shared"
NEW_RELEASE="$REPO_DIR/releases/$(date +%Y%m%d%H%M%S)"
git clone --depth 1 --branch main "$REPO" "$NEW_RELEASE"
mkdir -p "$SHARED_DIR/storage/app/public"
ln -sfn "$SHARED_DIR/.env" "$NEW_RELEASE/.env"
ln -sfn "$SHARED_DIR/storage/app/public" "$NEW_RELEASE/public/storage"
(
cd "$NEW_RELEASE"
composer install --no-dev --optimize-autoloader --no-interaction
php artisan migrate --force
)
ln -sfn "$NEW_RELEASE" "$REPO_DIR/current"
(
cd "$REPO_DIR/current"
php artisan config:cache
php artisan route:cache
php artisan view:cache
)
sudo systemctl reload php8.3-fpm
# نگه داشتن چند release آخر
cd "$REPO_DIR" && ls -dt releases/* | tail -n +6 | xargs -r rm -rf
اینجا public/storage فقط یک بار به shared وصل میشه و بین releaseها reuse میشه. storage:link داخل هر release لازم نیست، چون خودت لینک درست رو ساختی.
سوالات متداول
۱. php artisan storage:link خطای File already exists میده؛ چی کار کنم؟
یعنی توی public/ چیزی به اسم storage از قبل هست (فایل، پوشه یا لینک قدیمی). اگه مطمئنی چیز مهمی توش نیست، rm -rf public/storage بزن و دوباره php artisan storage:link رو اجرا کن. یا مستقیم php artisan storage:link --force بزن. برای پاک کردن لینک، لاراول دستور storage:unlink هم داره.
۲. symlink درسته ولی تصویر هنوز ۴۰۴ میده؛ چرا؟
چهار دلیل پرتکرار: disable_symlinks on توی Nginx، permission یا SELinux، اشتباه بودن root یا try_files، و کش مرورگر یا CDN که URL قدیمی رو نگه داشته. از جدول تشخیص اول مقاله شروع کن و لاگ Nginx رو هم نگاه کن.
۳. روی shared hosting بدون SSH چی کار کنم؟
از File Manager مربوط به cPanel یا Plesk، پوشهی واقعی storage داخل public_html رو بردار و symlink بساز به ../storage/app/public. اگه File Manager اجازهی symlink نمیده، از cron با مسیر درست PHP CLI استفاده کن. serve کردن فایل از route لاراول آخرین گزینهست و برای production پیشنهاد نمیشه.
۴. چرا بعد از هر deploy لینک میشکنه؟
چون اسکریپت deploy توی هر release یه symlink جدا میسازه که به shared اشاره نمیکنه. باید public/storage همیشه به یه مسیر shared مثل shared/storage/app/public وصل باشه تا آپلودها بین releaseها گم نشن.
۵. توی Docker که Nginx و app جدا هستن، symlink چطور باید کار کنه؟
symlink داخل کانتینر app کافی نیست. volume مربوط به storage باید روی کانتینر Nginx هم mount بشه (ترجیحاً read-only). در غیر این صورت Nginx به فایل واقعی نمیرسه و /storage/... چهارصدوچهار میده.
خلاصهی یه خطی: مطمئن شو public/storage یه symlink به storage/app/public (یا shared معادلشه)، Nginx اجازه میده symlink رو دنبال کنه، permission درسته، document root روی public/ هست، و توی deployهای atomic لینک به shared وصله.
اگه نمیخوای هر بار خودت درگیر Nginx و deploy و permission بشی، راهاندازی سرور لاراول و نگهداری پروژه رو میتونی به ما بسپری. جزئیاتش توی صفحهی نگهداری و امنیت سایت هست و از همونجا میتونی پروژهات رو بفرستی.
سوالی داشتی یا جایی گیر کردی، توی کامنتها بپرس.