خطأ vendor/autoload.php بعد نقل موقعك إلى استضافة مشتركة
باختصار: إذا رفع المطور موقعك المبني بـ PHP، مثل Laravel، إلى استضافة مشتركة، ثم ظهرت صفحة خطأ تقول إن الملف vendor/autoload.php غير موجود، فالموقع لا ينقصه سطر كود، بل ينقصه مجلد المكتبات كاملاً. توثيق Composer يشرح أن مجلد vendor هو المكان المعتاد لكل الكود الخارجي في المشروع، وينصح بإضافته إلى ملف التجاهل في git، لذلك لا يصل إلى الخادم عند الرفع من المستودع. الحل: تشغيل composer install على الخادم من ملف composer.lock، مع خيارات الإنتاج، أو بناء المجلد على جهاز بنفس إصدار PHP ثم رفعه، والتحقق من أن الخادم يملك الإضافات المطلوبة.
ما الذي يراه صاحب الموقع؟
صاحب مكتب تأمين في عمّان طلب من مطور مستقل نقل نظام عروض الأسعار من خادم قديم إلى استضافة مشتركة جديدة. المطور رفع الملفات من المستودع، وأنشأ قاعدة البيانات، ثم أرسل الرابط. عند فتحه ظهرت صفحة بيضاء فيها رسالة خطأ طويلة بالإنجليزية تذكر vendor وautoload.php. المطور قال: «الاستضافة ما فيها Composer»، ومزود الاستضافة قال: «الخطأ من الكود».
هذا مثال توضيحي لحالة متكررة عند نقل مواقع PHP إلى استضافات مشتركة. والحقيقة أن الطرفين على حق جزئياً: الكود سليم، لكن خطوة تثبيت المكتبات لم تُنفذ بعد الرفع.
لماذا لا يكون مجلد vendor في الملفات المرفوعة؟
Composer هو مدير الحزم في PHP. عندما يحتاج المشروع مكتبات خارجية، تُسجل في ملف composer.json، ثم ينزّلها Composer. توثيق Composer يقول إن أمر التثبيت ينزّل ملفات الحزم إلى مجلد vendor في المشروع، ويصف هذا المجلد بأنه المكان المعتاد لكل الكود الخارجي.
ويضيف التوثيق نصيحة: إذا كنت تستخدم git، فالأرجح أنك تريد إضافة vendor إلى ملف التجاهل، لأنك لا تريد إضافة كل هذا الكود الخارجي إلى المستودع. لذلك عندما يرفع المطور المشروع من المستودع، يصل كل شيء ما عدا المكتبات. وملف autoload.php الذي يبحث عنه المشروع موجود داخل vendor، فيفشل الموقع من أول سطر.
الملف الذي يضمن النسخ نفسها: composer.lock
إلى جانب composer.json يوجد ملف composer.lock. التوثيق يشرح أن إضافة هذا الملف إلى المستودع مهمة، لأنها تجعل كل من يجهّز المشروع يستخدم نفس إصدارات المكتبات بالضبط: الفريق، وخوادم الإنتاج، وأي نظام بناء. ويذكر أنه عند تشغيل install مع وجود ملف القفل، يثبّت Composer كل المكتبات المطلوبة لكن بالإصدارات المحددة في composer.lock.
السؤال الأول إذن: هل ملف composer.lock موجود في الملفات المرفوعة؟ إذا كان موجوداً، فالموقع الجديد سيحصل على المكتبات نفسها التي عمل بها على الخادم القديم.
الطريقة الأولى: تشغيل Composer على الخادم
كثير من الاستضافات المشتركة توفر وصولاً عبر SSH أو طرفية داخل لوحة التحكم، وبعضها يوفر Composer جاهزاً. إذا توفر ذلك، يشغّل المطور أمر التثبيت في مجلد المشروع.
للإنتاج، يذكر توثيق أوامر Composer خيارين مفيدين:
- --no-dev: يتخطى تثبيت المكتبات المذكورة في require-dev، أي أدوات التطوير والاختبار التي لا يحتاجها الموقع الحي.
- --optimize-autoloader: يحول طريقة تحميل الملفات إلى خريطة أصناف لتحميل أسرع. والتوثيق يقول إنه موصى به خصوصاً للإنتاج، لكنه ليس افتراضياً لأنه يأخذ وقتاً.
انتبه: الأمر المطلوب هو install لا update. أمر update يبحث عن أحدث الإصدارات المسموحة ويغيّر ملف القفل، وهذا قرار يُتخذ على جهاز التطوير ويُختبر، لا على الموقع الحي.
الطريقة الثانية: البناء على جهاز آخر ثم الرفع
إذا لم تسمح الاستضافة بتشغيل Composer، يمكن للمطور تشغيل أمر التثبيت بالخيارات نفسها على جهازه، ثم رفع مجلد vendor كاملاً مع المشروع.
الشرط المهم: أن يكون إصدار PHP على جهاز البناء مطابقاً أو متوافقاً مع إصدار الخادم، لأن بعض المكتبات تُختار حسب إصدار PHP. وهذا يقودنا إلى الخطوة التالية.
لماذا لا يُرفع كل شيء عبر FTP من البداية؟
قد يسأل صاحب العمل: لماذا لا ينسخ المطور المشروع كاملاً من الخادم القديم، بمجلد vendor، ويرفعه كما هو؟ أحياناً يعمل هذا، لكنه يحمل مخاطر:
- إذا كان إصدار PHP على الخادم الجديد مختلفاً، فقد لا تعمل بعض المكتبات المثبتة للإصدار القديم.
- مجلد vendor يحتوي آلاف الملفات الصغيرة، ورفعه عبر FTP بطيء، وقد ينقطع في المنتصف دون أن يلاحظ أحد أن ملفات ناقصة.
- إذا كانت على الخادم القديم مكتبات عُدّلت يدوياً، فستنتقل التعديلات دون توثيق.
لذلك التثبيت من ملف القفل أنظف، ويعطيك موقعاً يمكن إعادة بنائه في أي وقت.
تحقق من متطلبات الخادم
حتى بعد وجود vendor، قد يفشل الموقع إذا كان الخادم يفتقد إضافة PHP تحتاجها مكتبة ما. توثيق Composer يذكر أمر check-platform-reqs، الذي يتحقق من أن إصدار PHP والإضافات تطابق متطلبات الحزم المثبتة، ويذكر أنه يمكن استخدامه للتحقق من أن خادم الإنتاج يملك كل الإضافات اللازمة بعد تثبيت المشروع.
ويذكر التوثيق خيار --ignore-platform-reqs الذي يتجاهل هذه المتطلبات ويفرض التثبيت. لا تقبل هذا كحل دائم: إذا كانت إضافة مطلوبة غير موجودة، فالموقع سيتعطل لاحقاً عند أول صفحة تحتاجها. الحل الصحيح تفعيل الإضافة من لوحة الاستضافة، أو اختيار إصدار PHP المناسب.
نقطة أمان في Laravel
إذا كان المشروع مبنياً بـ Laravel، فهناك نقطة تتكرر مع الاستضافات المشتركة. توثيق النشر في Laravel يطلب أن يوجّه خادم الويب كل الطلبات إلى ملف public/index.php، ويحذر من نقل ملف index.php إلى جذر المشروع، لأن تقديم التطبيق من جذر المشروع يكشف ملفات إعداد حساسة للعامة على الإنترنت.
بعض المطورين، عندما لا يستطيعون تغيير المجلد الرئيسي للموقع في الاستضافة، يرفعون المشروع كله إلى المجلد العام. هذا قد يجعل ملفات مثل الإعدادات والمكتبات قابلة للوصول من المتصفح. اسأل المطور: هل المجلد الذي يفتحه النطاق هو public فقط؟
قائمة تسليم بعد النقل
- الموقع يفتح دون أخطاء، وصفحات الإدارة تعمل.
- ملف composer.lock موجود ومطابق للنسخة التي اختُبرت.
- المكتبات ثُبتت بخيارات الإنتاج، دون أدوات التطوير.
- أمر التحقق من متطلبات الخادم لا يُظهر نقصاً.
- النطاق يشير إلى مجلد public فقط في مشاريع Laravel.
- رسائل الخطأ التفصيلية لا تظهر للزوار.
أسئلة شائعة
شو يعني خطأ vendor/autoload.php not found؟
يعني أن مجلد المكتبات vendor غير موجود على الخادم، غالباً لأنه مستثنى من المستودع ولم يُشغّل أمر التثبيت بعد الرفع.
هل أشغّل composer install ولا composer update؟
install على الخادم، لأنه يثبّت الإصدارات المحددة في composer.lock. أما update فيغيّر الإصدارات ويُستخدم في بيئة التطوير.
الاستضافة ما فيها Composer، شو الحل؟
ثبّت المكتبات على جهاز بإصدار PHP متوافق مع الخادم، ثم ارفع مجلد vendor مع المشروع.
ليش الموقع اشتغل بس بعض الصفحات بتعطي خطأ؟
قد تكون إضافة PHP ناقصة. أمر check-platform-reqs يتحقق من تطابق الإضافات مع متطلبات المكتبات.
إذا تعطل موقعك بعد نقله إلى استضافة جديدة، اكتب لنا ونكمل التثبيت معك.