صور موقع Laravel مكسورة بعد النقل: أمر storage:link وAPP_URL
باختصار: إذا كان موقعك المبني بـ Laravel يقبل رفع الصور، مثل صور العقارات أو المنتجات أو الشهادات، لكنها تظهر كمربعات مكسورة أو تعطي خطأ 404 بعد النقل إلى خادم جديد، فالسبب الأكثر شيوعاً أن الرابط الرمزي بين مجلد التخزين والمجلد العام غير موجود. توثيق Laravel يوضح أن قرص «public» يخزن الملفات افتراضياً في storage/app/public، وأن جعلها متاحة على الويب يحتاج رابطاً رمزياً إلى public/storage يُنشأ بأمر php artisan storage:link. وإذا كانت الروابط تشير إلى عنوان خاطئ، فراجع APP_URL.
المشهد المعتاد
مكتب عقارات في عمّان لديه موقع يضيف فيه الموظفون الشقق المعروضة مع صورها. على الخادم القديم كان كل شيء يعمل. بعد النقل إلى استضافة جديدة، ظهرت الإعلانات بنصوصها وأسعارها، لكن كل الصور مكسورة. الموظفون يرفعون صوراً جديدة فتختفي هي أيضاً، رغم أن رسالة «تم الرفع بنجاح» تظهر.
عندما تحقق المطور، وجد أن الملفات موجودة فعلاً على الخادم، داخل مجلد التخزين. المشكلة أن الزائر لا يستطيع الوصول إليها. هذا مثال توضيحي لحالة متكررة.
لماذا لا تكون الملفات المرفوعة متاحة مباشرة؟
في Laravel، المجلد الذي يراه الزائر هو مجلد public فقط. أما مجلد storage فهو خارج متناول الويب، وهذا مقصود: فيه ملفات السجلات والجلسات وملفات أخرى لا يجب أن يصل إليها أحد.
توثيق Laravel يشرح أن قرص public في إعدادات نظام الملفات مخصص للملفات التي يُراد أن تكون متاحة للعامة، وأنه افتراضياً يستخدم المحرك المحلي ويخزن الملفات في storage/app/public. ولجعل هذه الملفات متاحة من الويب، يجب إنشاء رابط رمزي من المجلد المصدر storage/app/public إلى المجلد الهدف public/storage.
الرابط الرمزي يشبه «اختصاراً» في نظام التشغيل: عندما يطلب الزائر ملفاً من /storage/...، يوجهه الخادم إلى مجلد التخزين الحقيقي.
الإصلاح الأساسي: أمر واحد
التوثيق يذكر أن الرابط يُنشأ بالأمر:
php artisan storage:link
بعد إنشاء الرابط، يمكن إنشاء روابط الملفات بالدالة asset، مثل asset('storage/file.txt')، أو عبر Storage::url. هذا الأمر يُشغّل مرة واحدة على كل خادم، لكنه يُنسى كثيراً عند النقل، لأنه ليس جزءاً من الملفات التي تُنسخ.
لماذا يختفي الرابط عند النقل؟
هناك عدة طرق شائعة يضيع بها الرابط:
- نسخة جديدة من المستودع: إذا نزّل المطور المشروع من Git على الخادم الجديد، فالرابط غير موجود لأنه لا يُحفظ عادة في المستودع.
- النقل بملف مضغوط أو FTP: بعض أدوات النقل لا تحفظ الروابط الرمزية، فتنسخها كمجلد عادي أو تتجاهلها. قد ترى مجلد public/storage موجوداً، لكنه نسخة قديمة فارغة لا تتصل بالتخزين الحقيقي.
- الصور الجديدة تذهب إلى مكان والقديمة في مكان آخر: إذا نُسخ المجلد بدل الرابط، تُحفظ الصور الجديدة في storage/app/public بينما يقرأ الموقع من نسخة جامدة في public/storage.
إذا كان public/storage مجلداً عادياً لا رابطاً، فيجب حذفه بحذر بعد التأكد من عدم وجود ملفات فيه لا توجد في التخزين، ثم تشغيل أمر الرابط من جديد. ويذكر التوثيق أيضاً أمر storage:unlink لحذف الروابط المعرفة في الإعدادات.
السبب الثاني: رابط يشير إلى عنوان خاطئ
أحياناً تكون الصورة متاحة فعلاً، لكن الموقع يكتب رابطها بشكل خاطئ، مثل http://localhost/storage/... أو عنوان النطاق القديم. في إعدادات قرص public كما يعرضها التوثيق، خيار url مبني على متغير APP_URL مضافاً إليه /storage. إذا بقي APP_URL على قيمة جهاز المطور أو النطاق القديم، ستُبنى كل روابط الصور عليه.
افحص ذلك بسهولة: افتح صفحة فيها صورة مكسورة، واضغط عليها بزر الفأرة الأيمن واختر نسخ عنوان الصورة. إذا كان العنوان لا يبدأ بنطاقك الحالي مع https، فالمشكلة في الإعداد لا في الرابط الرمزي.
السبب الثالث: الملف رُفع إلى القرص الخاص
توثيق Laravel يذكر أن جذر القرص المحلي الافتراضي هو storage/app/private. إذا كان كود الرفع يحفظ الصور في القرص المحلي بدلاً من قرص public، فستُحفظ في المجلد الخاص، ولن يصل إليها الزائر حتى مع وجود الرابط الرمزي. وهذا جيد في بعض الحالات، مثل ملفات هويات أو عقود لا يجب أن تكون عامة، لكنه خطأ لصور الإعلانات.
اسأل المطور سؤالاً مباشراً: «على أي قرص تُحفظ صور الإعلانات؟» يجب أن يكون الجواب قرص public للصور العامة.
الملفات الحساسة لا تضعها في public أصلاً
بعض المواقع ترفع ملفات لا يجب أن يراها الجميع: سير ذاتية في صفحة الوظائف، أو صور هويات، أو تقارير. هذه لا تُوضع في قرص public. التوثيق يشرح طريقة لإنشاء روابط مؤقتة للملفات المخزنة بالمحرك المحلي ومحرك S3، عبر الدالة temporaryUrl التي تستقبل مسار الملف ووقت انتهاء صلاحية الرابط. بهذه الطريقة يحصل الموظف المخول على رابط مؤقت، ولا يصبح الملف متاحاً لكل من يعرف اسمه.
الاستضافة المشتركة ومجلد public_html
في كثير من خطط الاستضافة المشتركة، المجلد الذي يخدم الموقع اسمه public_html، لا public. إذا رُفع مشروع Laravel بحيث يختلف المجلد العام عن المتوقع، قد يُنشأ الرابط في مكان لا يقرأ منه الخادم. هنا يحتاج المطور أن يتأكد أين يشير جذر الموقع فعلاً، وأن الرابط موجود داخل المجلد الذي يخدمه الخادم. التوثيق يذكر أن إعدادات نظام الملفات تسمح بتعريف روابط رمزية إضافية في قسم links، وكل الروابط المعرفة هناك تُنشأ عند تشغيل الأمر.
ولاحظ أن بعض الاستضافات لا تسمح بإنشاء الروابط الرمزية أو بتشغيل أوامر Artisan. اسأل مزود الاستضافة قبل النقل، لا بعده.
لا تنسَ مجلد التخزين في النسخ الاحتياطي
نقطة مرتبطة يغفل عنها كثيرون: بما أن الصور الحقيقية تعيش في storage/app/public، فهذا المجلد هو ما يجب أن يدخل في النسخ الاحتياطي، لا public/storage الذي هو مجرد رابط. إذا كانت خطة النسخ تأخذ مجلد public فقط، فقد تبدو النسخة كاملة بينما هي خالية من كل صور الإعلانات. راجع مع مزود الاستضافة أو المطور ما الذي تحتويه النسخة فعلاً، وجرّب استرجاع صورة واحدة منها.
قائمة فحص بعد كل نقل
- هل public/storage رابط رمزي فعلاً وليس مجلداً عادياً؟
- هل شُغّل أمر storage:link على الخادم الجديد؟
- هل APP_URL مضبوط على النطاق الحالي مع https؟
- هل كود الرفع يحفظ الصور العامة على قرص public؟
- هل الملفات الحساسة على قرص خاص وتُعرض بروابط مؤقتة؟
- هل الرابط موجود في المجلد الذي يخدمه الخادم فعلاً؟
- ارفع صورة تجريبية وافتحها من هاتف خارج شبكة المكتب.
أسئلة شائعة
ليش صور الموقع صارت مكسورة بعد نقل الاستضافة؟
غالباً لأن الرابط الرمزي بين storage/app/public وpublic/storage غير موجود على الخادم الجديد. شغّل php artisan storage:link.
الصور الجديدة بتنرفع بس ما بتبين، ليش؟
ربما public/storage مجلد عادي منسوخ وليس رابطاً، أو أن الصور تُحفظ على القرص الخاص بدل قرص public.
رابط الصورة فيه localhost، شو الحل؟
صحّح قيمة APP_URL لأن رابط قرص public يُبنى عليها.
هل أحط السير الذاتية بنفس المكان؟
لا. احفظها على قرص خاص واعرضها بروابط مؤقتة للموظفين المخولين.
إذا كانت صور موقعك المبني بـ Laravel مكسورة بعد النقل، تواصل معنا ونراجع التخزين والروابط معك.