خطأ Vite manifest not found في Laravel: موقع بلا تنسيق بعد النشر
باختصار: إذا ظهرت في موقعك المبني بـ Laravel صفحة خطأ تقول «Vite manifest not found»، أو فتح الموقع دون أي تنسيق بعد نقله إلى خادم جديد، فالسبب غالباً أن ملفات الواجهة لم تُبنَ للإنتاج. توثيق Laravel يشرح أن أمر npm run build يُصدر نسخاً مضغوطة ومرقّمة من ملفات التطبيق جاهزة للنشر، وأن توجيه @vite في وضع البناء يحمّل هذه الملفات المجمعة. وتوثيق Vite يوضح أن البناء يولّد ملفاً اسمه manifest.json داخل مجلد .vite بجانب الملفات الأخرى، وهو الخريطة التي يقرأ منها Laravel أسماء الملفات. الحل: تشغيل أمر البناء ونشر مجلد الملفات الناتجة مع الموقع، والتأكد من عدم بقاء ملف خادم التطوير على الخادم الحي.
كيف تبدو المشكلة من جهتك؟
مركز تدريب مهني في الزرقاء لديه موقع تسجيل في الدورات مبني بـ Laravel. نقل المطور الموقع إلى استضافة جديدة، وثبّت مكتبات PHP، وربط قاعدة البيانات. لكن عند فتح الموقع ظهرت صفحة خطأ فيها كلمة manifest. في محاولة أخرى، اختفى الخطأ لكن الموقع ظهر نصوصاً سوداء على خلفية بيضاء، بلا ألوان ولا قوائم، وأزرار التسجيل لا تعمل.
المطور قال إن الموقع «يشتغل عنده». وهذا صحيح، لأن جهازه يشغّل خادم تطوير Vite أثناء العمل. هذا مثال توضيحي لحالة متكررة عند نشر مشاريع Laravel الحديثة.
ما علاقة Vite بموقع Laravel؟
Laravel يستخدم Vite لتجميع ملفات CSS وJavaScript. توثيق Laravel يذكر أن هناك طريقتين لتشغيله:
- npm run dev: يشغّل خادم تطوير Vite، وهو مفيد أثناء التطوير المحلي لأنه يكتشف التغييرات فوراً.
- npm run build: يبني الملفات ويرقّمها للإنتاج.
وفي القوالب، يستخدم المطور توجيه @vite. التوثيق يشرح أن هذا التوجيه يكتشف خادم التطوير تلقائياً إن كان يعمل، ويحقن ما يلزم لإعادة التحميل الفوري. أما في وضع البناء، فيحمّل الملفات المجمعة والمرقمة، بما فيها CSS المستورد.
إذن عندما لا يوجد خادم تطوير ولا ملفات مبنية، لا يجد Laravel ما يحمّله.
ما هو ملف manifest؟
عند البناء للإنتاج، لا تبقى أسماء الملفات كما هي. توثيق Vite عن التكامل مع أنظمة الخادم يشرح أنه بعد تشغيل أمر البناء، يُولّد ملف .vite/manifest.json بجانب الملفات الأخرى، وأنه يمكن استخدامه لإنشاء الروابط بأسماء الملفات التي تحمل بصمة.
بلغة بسيطة: ملف app.js الذي كتبه المطور يصبح بعد البناء ملفاً باسم فيه رموز تتغير مع كل بناء. والملف manifest يقول لـ Laravel: «الملف الذي تبحث عنه اسمه الآن كذا». إذا لم يوجد هذا الملف، يظهر خطأ «Vite manifest not found».
لماذا تتغير أسماء الملفات أصلاً؟
قد يسأل صاحب الموقع: لماذا لا تبقى الأسماء ثابتة ونتخلص من هذه الخريطة؟ السبب هو التخزين المؤقت. المتصفحات وشبكات توزيع المحتوى تحتفظ بنسخ من ملفات CSS وJavaScript لتسريع الموقع. إذا بقي اسم الملف ثابتاً بعد تعديل التصميم، قد يرى الزوار النسخة القديمة أياماً. عندما يتغير الاسم مع كل بناء، يطلب المتصفح الملف الجديد فوراً.
توثيق Laravel يصف أمر البناء بأنه يرقّم الملفات ويجمعها، وتوثيق Vite يذكر أن ملف manifest يُستخدم لإنشاء الروابط بأسماء الملفات التي تحمل بصمة. الخريطة إذن ليست تعقيداً زائداً، بل ما يجعل تحديثات التصميم تصل إلى الزبائن مباشرة. ولهذا يجب أن يُعاد البناء ويُرفع ملف manifest الجديد مع كل تغيير في الواجهة.
الخطوات الصحيحة للنشر
- تأكد من Node وNPM حيث يتم البناء: توثيق Laravel يقول إنه يجب التأكد من تثبيت Node.js بإصدار 16 فما فوق، وNPM، قبل تشغيل Vite.
- ثبّت حزم الواجهة: بأمر تثبيت حزم npm في مجلد المشروع.
- شغّل npm run build: لإنتاج الملفات المرقمة وملف manifest.
- انشر الملفات الناتجة: المجلد الذي يحتوي الملفات المبنية يجب أن يصل إلى الخادم داخل المجلد العام للموقع. كثير من المشاريع تستثني هذا المجلد من المستودع، لذلك قد لا يصل عند الرفع من git، تماماً مثل مجلد مكتبات PHP.
- لا تشغّل خادم التطوير على الخادم الحي: npm run dev للتطوير فقط.
إذا كانت الاستضافة لا تدعم Node
كثير من الاستضافات المشتركة لا توفر Node. هذا ليس عائقاً: يمكن تشغيل أمر البناء على جهاز المطور أو في نظام بناء آلي، ثم رفع الملفات المبنية فقط. الخادم الحي لا يحتاج Node ليعرض الموقع، بل يحتاج الملفات الناتجة وملف manifest.
الحالة المعاكسة: الموقع يحاول الاتصال بخادم التطوير
إذا ظهر الموقع دون تنسيق، وفي أدوات المطور في المتصفح طلبات فاشلة إلى عنوان محلي مثل localhost مع منفذ، فالأرجح أن Laravel يظن أن خادم التطوير يعمل. توثيق Laravel يذكر أن التوجيه يكتشف خادم التطوير، ويعرض بين خيارات التخصيص طريقة لتغيير مسار ملف «hot» الذي يُستخدم لذلك. عملياً، إذا نُسخ هذا الملف من جهاز المطور إلى الخادم الحي، يحاول الموقع تحميل ملفاته من جهاز غير موجود. اطلب من المطور التأكد أن هذا الملف ليس ضمن الملفات المنشورة.
إذا كانت الملفات على نطاق منفصل
بعض المواقع تضع الملفات الثابتة على شبكة توزيع محتوى بنطاق مختلف. توثيق Laravel يذكر أنه في هذه الحالة يجب تحديد متغير البيئة ASSET_URL في ملف .env، وبعدها تُسبق روابط الملفات المعاد كتابتها بهذا العنوان. إذا نُسي هذا المتغير، قد يبحث الموقع عن الملفات في المكان الخطأ.
مسار بناء مخصص
التوثيق يذكر أيضاً إمكانية تحديد مسار البناء عند استدعاء التوجيه، وتخصيص مجلد البناء واسم ملف manifest. إذا كان المطور السابق قد غيّر هذه الإعدادات، فقد يبحث Laravel عن الملف في مجلد غير الذي يتوقعه المطور الجديد. لذلك عند تسليم المشروع، اطلب توثيق أي تخصيص من هذا النوع.
قائمة تسليم
- أمر البناء يعمل دون أخطاء على جهاز البناء.
- ملف manifest موجود في مجلد البناء داخل المجلد العام على الخادم.
- لا يوجد ملف خادم التطوير على الخادم الحي.
- الموقع يظهر بتنسيقه الكامل في نافذة خاصة.
- أدوات المطور في المتصفح لا تُظهر طلبات فاشلة لملفات CSS أو JavaScript.
- بعد كل تعديل على الواجهة، يُعاد البناء ويُنشر من جديد.
أسئلة شائعة
شو يعني خطأ Vite manifest not found؟
يعني أن Laravel لم يجد ملف manifest الذي يولّده أمر البناء، غالباً لأن npm run build لم يُشغّل أو أن ملفاته لم تُرفع.
الموقع طالع بدون تنسيق بعد النقل، ليش؟
إما أن الملفات المبنية غير موجودة، أو أن الموقع يحاول تحميل ملفاته من خادم تطوير غير موجود.
الاستضافة ما فيها Node، شو أعمل؟
ابنِ الملفات على جهاز آخر بأمر npm run build، وارفع الملفات الناتجة فقط.
هل أشغل npm run dev على السيرفر؟
لا. هذا الأمر للتطوير المحلي. للإنتاج استخدم npm run build.
إذا ظهر موقعك بلا تنسيق أو بخطأ manifest بعد النشر، تواصل معنا ونكمل البناء معك.