إصلاح أخطاء 500 في Laravel: قائمة تحقق مجرّبة

ابدأ بالسجل

صفحة «500 Server Error» تخبرك فقط بأن شيئًا ما فشل. السبب موجود في السجلات. انظر أولًا في storage/logs/laravel.log (أو ملف اليوم إذا كنت تستخدم سجلات يومية). إذا كان فارغًا، فقد وقع الخطأ قبل أن يتمكن Laravel من تسجيله، فافحص بعدها سجل أخطاء خادم الويب وسجل PHP-FPM أو LiteSpeed.

لا تضبط APP_DEBUG=true على موقع مباشر لرؤية الخطأ. فذلك يكشف تتبعات الأخطاء وقيم البيئة وأحيانًا كلمات المرور لأي شخص يفتح الصفحة. اقرأ السجلات بدلًا من ذلك.

tail -n 100 storage/logs/laravel.log
# no entries? check the server logs, for example:
tail -n 100 /var/log/nginx/error.log

1. الصلاحيات

يجب أن يستطيع Laravel الكتابة في storage وbootstrap/cache. بعد الرفع عبر FTP أو النشر بمستخدم آخر، غالبًا ما تصبح هذه المجلدات ملكًا لحساب خطأ. سيظهر في السجل «Permission denied» أو «failed to open stream». امنح مستخدم خادم الويب صلاحية الكتابة على هذين المجلدين فقط، ولا تجعل المشروع كله قابلًا للكتابة أبدًا.

2. البيئة وذاكرة الإعدادات المؤقتة

قيمة مفقودة أو خاطئة في .env سبب كلاسيكي: غياب APP_KEY («No application encryption key has been specified»)، أو كلمة مرور قاعدة بيانات خاطئة، أو برنامج تخزين مؤقت غير موجود على الخادم. تذكّر أنه بعد php artisan config:cache لا يقرأ Laravel ملف .env أثناء التشغيل، وأي استدعاء لـ env() خارج ملفات الإعدادات يعيد null. عدّل .env ثم أعد بناء الذاكرة المؤقتة.

3. الاعتماديات والتحميل التلقائي

ظهور «Class not found» مباشرة بعد النشر يعني عادةً أن مجلد vendor لم يُحدَّث أو أن المحمّل التلقائي قديم. شغّل composer install مع --no-dev و--optimize-autoloader على الخادم، وتأكد أن إصدار PHP وامتداداته على الخادم يطابقان ما يتطلبه composer.lock.

4. قاعدة البيانات والترحيلات

كود جديد يتوقع عمودًا غير موجود بعد في قاعدة البيانات ينتج أخطاء SQL مثل «Unknown column» أو «Base table or view not found». نفّذ الترحيلات المعلقة مع --force في الإنتاج. وتحقق أيضًا من إمكانية الوصول إلى قاعدة البيانات وRedis وأنهما لم يستنفدا الاتصالات.

5. الذاكرات المؤقتة القديمة وعمال الطوابير

قد تشير المسارات والعروض والإعدادات المخزنة من الإصدار السابق إلى كود لم يعد موجودًا. امسحها وأعد بناءها في كل نشر. وعمال الطوابير عمليات طويلة التشغيل: يحتفظون بالكود القديم في الذاكرة حتى إعادة تشغيلهم، فقد تفشل المهام بأخطاء لم تعد تطابق كودك.

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
php artisan config:cache && php artisan route:cache && php artisan view:cache
php artisan queue:restart

6. الذاكرة والمهل والخدمات الخارجية

قد تتجاوز عمليات التصدير الكبيرة ومعالجة الصور والاستعلامات غير المحدودة قيمتي memory_limit أو max_execution_time في PHP. انقل الأعمال الثقيلة إلى مهام الطوابير وعالج البيانات على دفعات. ويجب أن يكون لكل استدعاء لواجهة خارجية مهلة وبديل، حتى لا يُسقط مزود بطيء صفحاتك. انتبه لفرق الرموز: الخطأ 502 أو 504 يشير غالبًا إلى PHP-FPM أو مهلة الوسيط، لا إلى استثناء في التطبيق.

امنع الخطأ التالي

• استخدم سكربت نشر واحدًا ينفذ دائمًا الخطوات نفسها بالترتيب نفسه.
• أضف تتبعًا للأخطاء (مثل Sentry أو Flare) لتعرف بالأخطاء قبل عملائك.
• راقب مسار الصحة /up المضمَّن في Laravel، إضافة إلى صفحة تستعلم من قاعدة البيانات.
• أبقِ بيئة الاختبار أقرب ما يمكن إلى الإنتاج: الإصدار نفسه من PHP والامتدادات وبرامج التخزين المؤقت.