لینک storage در لاراول 404 می‌ده؟ رفع مشکل Nginx

event 14 آبان 1405
update به‌روزرسانی: 12 آبان 1405
timer 12 دقیقه
کاور مقاله‌ی لینک storage در لاراول 404: پوشه‌ی public با لینک شکسته به storage/app/public، زنجیر پاره و بج ۴۰۴ روی پس‌زمینه‌ی سرمه‌ای فیروزه‌ای
favorite 0

روی 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 و worker www-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 بشی، راه‌اندازی سرور لاراول و نگهداری پروژه رو می‌تونی به ما بسپری. جزئیاتش توی صفحه‌ی نگهداری و امنیت سایت هست و از همون‌جا می‌تونی پروژه‌ات رو بفرستی.

سوالی داشتی یا جایی گیر کردی، توی کامنت‌ها بپرس.

Captain Code
verified
نویسنده

Captain Code

مشاهده پروفایل arrow_back

عاشق دنیای کدنویسی و به اشتراک‌گذاری دانش. ما در کاپیتان کد تلاش می‌کنیم بهترین محتوا را برای شما تولید کنیم.

مفید بود؟ لایک کنید 👋
اشتراک‌گذاری:

پرسش‌های متداول

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/...` چهارصدوچهار می‌ده.

کاپیتان کد

این را برای پروژه‌ات می‌خواهی؟

پروژه را به کاپیتان کد بسپار، یا با نیکس همین مسئله را دیباگ کن.

forum

نظرات

lock_person

برای ثبت نظر وارد شوید

برای شرکت در گفتگو، لطفاً ابتدا وارد حساب کاربری‌تان شوید.

login ورود
chat_bubble_outline

هنوز نظری ثبت نشده

اولین نفری باشید که نظر خود را درباره این مطلب به اشتراک می‌گذارد!