إنتقل إلى المحتوى الرئيسي

المشكلات الشائعة وحلولها

دليل شامل لأكثر المشكلات شيوعًا وحلولها.

مشكلات التثبيت​

صفحة بيضاء فارغة بعد التثبيت​

السبب: عادةً ما تكون مشكلة في صلاحيات الملفات.

الحل:

# تحقق من سجل Laravel
tail -50 storage/logs/laravel.log

# إصلاح الصلاحيات
sudo chmod -R 775 storage bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache

أخطاء "Class Not Found"​

السبب: تبعيات Composer غير مثبتة أو لم يُنشأ محمّل التلقائي.

الحل:

composer install --no-dev --optimize-autoloader
php artisan config:clear

يعرض المثبّت "Already Installed"​

السبب: ملف storage/installed.lock موجود.

الحل: إذا أردت إعادة تشغيل المثبّت:

rm storage/installed.lock

ثم زر /install مجددًا.

CSS/JS لا يُحمَّل (صفحة بدون تنسيق)​

السبب: رابط التخزين مفقود أو مشكلة في مسار الأصول.

الحل:

php artisan storage:link
php artisan config:clear
php artisan view:clear

تأكد أيضًا من أن APP_URL في .env يطابق نطاقك الفعلي (بما في ذلك https://).

مشكلات قاعدة البيانات​

"SQLSTATE[HY000] [2002] Connection Refused"​

السبب: MySQL لا يعمل أو المضيف خاطئ.

الحل:

  • تحقق من تشغيل MySQL: sudo systemctl status mysql
  • جرّب 127.0.0.1 بدلاً من localhost في .env
  • تحقق من المنفذ (الافتراضي: 3306)

"SQLSTATE[HY000] [1045] Access Denied"​

السبب: بيانات اعتماد قاعدة البيانات خاطئة.

الحل:

  • تحقق من اسم المستخدم/كلمة المرور في .env
  • اختبر الاتصال: mysql -u your_user -p your_database
  • أعد منح الصلاحيات:
GRANT ALL PRIVILEGES ON feedbackpulse.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

الرموز التعبيرية تظهر كـ ????​

السبب: ترميز قاعدة البيانات هو utf8 بدلاً من utf8mb4.

الحل:

ALTER DATABASE feedbackpulse CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

مشكلات خادم الويب​

جميع المسارات تُرجع 404​

إصلاح Apache:

sudo a2enmod rewrite
sudo systemctl restart apache2

تأكد من ضبط AllowOverride All في المضيف الافتراضي.

إصلاح Nginx: تأكد من وجود هذا في كتلة الخادم:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

502 Bad Gateway (Nginx)​

السبب: PHP-FPM لا يعمل أو مسار Socket خاطئ.

الحل:

sudo systemctl restart php8.4-fpm
# تحقق من مسار Socket
ls /var/run/php/php8.4-fpm.sock

413 Request Entity Too Large​

السبب: حد حجم الرفع منخفض جدًا.

الإصلاح (Nginx):

client_max_body_size 20M;

الإصلاح (PHP):

upload_max_filesize = 20M
post_max_size = 25M

مشكلات المصادقة​

"CSRF Token Mismatch" (خطأ 419)​

السبب: انتهت صلاحية الجلسة أو مشكلة في الكوكيز.

الحل:

  • امسح كوكيز المتصفح وأعد المحاولة
  • تحقق من SESSION_DOMAIN في .env (اضبطه على .yourdomain.com للنطاقات الفرعية)
  • تأكد من ضبط SESSION_SECURE_COOKIE=true فقط عند استخدام HTTPS

تعذّر تسجيل الدخول بعد إعادة تعيين كلمة المرور​

السبب: المتصفح احتفظ بذاكرة الجلسة القديمة.

الحل: امسح كوكيز المتصفح أو استخدم نافذة التصفح الخاص.

تسجيل الدخول الاجتماعي يُرجع خطأ​

السبب: عدم تطابق عنوان URL لرد الاتصال.

الحل: تأكد من أن عنوان URL لرد الاتصال في وحدة تحكم Google/GitHub يطابق تمامًا:

  • Google: https://yourdomain.com/auth/google/callback
  • GitHub: https://yourdomain.com/auth/github/callback

مشكلات الدفع​

راجع مشكلات بوابة الدفع للحصول على تفاصيل استكشاف أخطاء الدفع.

مشكلات البريد الإلكتروني​

راجع مشكلات إرسال البريد الإلكتروني للحصول على تفاصيل استكشاف أخطاء البريد الإلكتروني.

مشكلات الأداء​

راجع تحسين الأداء للحصول على نصائح التحسين.

مشكلات الذاكرة المؤقتة​

عند الشك، امسح جميع الذاكرات المؤقتة:

php artisan optimize:clear

يمسح هذا:

  • ذاكرة الإعداد المؤقتة
  • ذاكرة المسارات المؤقتة
  • ذاكرة العرض المؤقتة
  • ذاكرة التطبيق المؤقتة
  • ذاكرة الفئات المُجمَّعة المؤقتة

وضع التشخيص (مؤقت)​

لرؤية رسائل الخطأ التفصيلية:

  1. عدّل .env:
APP_DEBUG=true
LOG_LEVEL=debug
  1. أعِد تكرار الخطأ
  2. تحقق من صفحة الخطأ أو storage/logs/laravel.log
  3. فورًا اضبط APP_DEBUG=false عند الانتهاء!
تحذير

لا تترك أبدًا APP_DEBUG=true في الإنتاج. يكشف عن معلومات حساسة.

الحصول على المساعدة​

إذا لم يحل أي مما سبق مشكلتك:

  1. تحقق من storage/logs/laravel.log للحصول على سجل الخطأ الكامل
  2. تحقق من سجل خطأ خادم الويب (/var/log/nginx/error.log أو /var/log/apache2/error.log)
  3. ابحث في تعليقات عنصر CodeCanyon عن مشكلات مماثلة
  4. افتح تذكرة دعم مع:
    • رسالة الخطأ (من السجل)
    • إصدار PHP (php -v)
    • إصدار Laravel
    • تفاصيل الخادم (نظام التشغيل، خادم الويب، إصدار MySQL)
    • خطوات إعادة الإنتاج