Question 1

فشل عملية البناء (Build failed)

Accepted Answer

العرض: يظهر خطأ أحمر في الشات: Build failed أو Failed to resolve import، ولا يتمّ تحديث المعاينة.

السبب: استيراد ملفّ أو حزمة غير موجودة، خطأ نحوي في TSX، أو تعارض في مسارات TanStack Router.

التشخيص: افتح تبويب Console وابحث عن أوّل خطأ أحمر (السطر والملفّ). — افحص آخر تعديل قبل الفشل — عادةً الاستيراد أو المسار الجديد هو السبب. — تأكّد أنّ اسم الملف في createFileRoute مطابق تمامًا للمسار في src/routes.

الحلّ: أنشئ الملف المفقود أو ثبّت الحزمة عبر bun add، وأصلح مطابقة createFileRoute مع اسم الملف. لا تعدّل src/routeTree.gen.ts يدويًا.

التحقّق: أعد فتح المعاينة — يجب أن تختفي رسالة Build failed وتظهر الصفحة بشكل طبيعي.

Question 2

خطأ عند النشر (Publish/Deploy)

Accepted Answer

العرض: زر Publish يفشل، أو الرابط المنشور يعرض شاشة بيضاء / خطأ 500 رغم أنّ المعاينة تعمل.

السبب: الفرق بين بيئة المعاينة وبيئة الإنتاج: متغيّرات بيئة ناقصة، استخدام مكتبة Node-only داخل Worker، أو استدعاء دالّة خادم محميّة من مسار عام.

التشخيص: افتح Server Function Logs للبيئة المنشورة وابحث عن أوّل خطأ. — تحقّق أنّ جميع الأسرار مضافة في Cloud → Secrets للبيئة المنشورة وليس فقط للتطوير. — تأكّد أنّ أيّ dependency ليست Node-only (sharp, puppeteer, canvas…).

الحلّ: أضف الأسرار المفقودة، استبدل حزم Node-only بأخرى متوافقة مع Cloudflare Workers، ولا تستدعِ Server Functions محميّة داخل loader لمسار عام.

التحقّق: افتح الرابط المنشور في نافذة تصفّح خفيّ — يجب أن تظهر الصفحة بلا أخطاء، وتُسجَّل الطلبات في Logs بحالة 200.

Question 3

مشاكل تسجيل الدخول

Accepted Answer

العرض: المستخدم يضغط دخول ولا شيء يحدث، أو يعود إلى صفحة الدخول، أو يظهر Unsupported provider.

السبب: مزوّد OAuth غير مُفعّل، أو redirect_uri لا يطابق النطاق، أو الجلسة لا تُحفظ (persistSession) بعد التحديث.

التشخيص: افتح Console وابحث عن رسائل من supabase.auth. — تحقّق أنّ redirect_uri يستخدم window.location.origin وليس مسارًا محميًّا. — تأكّد أنّ مزوّد Google/Email مُفعّل في إعدادات المصادقة.

الحلّ: فعّل مزوّد الدخول من إعدادات Auth، اضبط redirect_uri إلى ${window.location.origin}/auth/callback، وتأكّد أنّ عميل Supabase يستخدم persistSession: true.

التحقّق: سجّل الدخول ثم حدّث الصفحة — يجب أن تبقى الجلسة نشطة ويظهر بريد المستخدم في الواجهة.

Question 4

أخطاء RLS و permission denied

Accepted Answer

العرض: الاستعلامات تعيد صفوفًا فارغة أو رسالة permission denied for table X رغم أنّ البيانات موجودة.

السبب: الجدول بلا سياسات RLS مناسبة، أو ناقصه GRANT للأدوار (authenticated / anon)، أو السياسة تعتمد على auth.uid() والمستخدم غير مسجّل.

التشخيص: افحص وجود ENABLE ROW LEVEL SECURITY و CREATE POLICY على الجدول. — تأكّد من GRANT SELECT/INSERT/UPDATE/DELETE للدور المناسب في نفس الهجرة. — اختبر الاستعلام بمستخدم مسجّل حقيقي وليس anon.

الحلّ: أضف GRANT للأدوار المطلوبة، ثم CREATE POLICY محدّدة لكل عملية (SELECT/INSERT/UPDATE/DELETE) مستندة إلى auth.uid() = user_id.

التحقّق: سجّل الدخول وشغّل الاستعلام — يجب أن ترى صفوف المستخدم فقط دون رسالة permission denied.

Question 5

خطأ CORS عند استدعاء API

Accepted Answer

العرض: الكونسول يعرض: Access to fetch has been blocked by CORS policy.

السبب: الخادم الخارجي لا يرسل رأس Access-Control-Allow-Origin، أو مسار /api الداخلي بلا معالج OPTIONS ولا رؤوس CORS في استجابات الخطأ.

التشخيص: افتح تبويب Network وابحث عن طلب OPTIONS فاشل قبل الطلب الحقيقي. — تحقّق من أنّ الرأس Access-Control-Allow-Origin موجود في الاستجابة. — تأكّد أنّ Access-Control-Allow-Headers يشمل كل رأس يرسله العميل.

الحلّ: أنشئ server route كـ proxy يستدعي الخارجي من الخادم، أو أضف معالج OPTIONS ورؤوس CORS في كل استجابة (بما فيها استجابات الأخطاء).

التحقّق: أعد الطلب في المتصفّح — يجب أن يعود بحالة 200 دون تحذير CORS في الكونسول.

Question 6

أسرار البيئة (Environment Secrets)

Accepted Answer

العرض: process.env.X تعيد undefined، أو المفتاح يظهر فارغًا داخل server function.

السبب: قراءة process.env في module scope تحدث قبل حقن الأسرار، أو استخدام بادئة VITE_ لسرّ يجب أن يبقى على الخادم فقط.

التشخيص: تحقّق أنّ السرّ مضاف في Cloud → Secrets وليس في ملفّ .env محلّي فقط. — تأكّد أنّ القراءة تحدث داخل .handler() وليس على مستوى الوحدة. — للأسرار الخادمية: لا تستخدم بادئة VITE_ ولا تقرأها في مكوّنات الواجهة.

الحلّ: اقرأ process.env داخل handler الدالة، أضف السرّ من واجهة الأسرار، واستعمل VITE_ فقط للقيم العامّة غير الحساسة.

التحقّق: شغّل الدالّة وسجّل typeof process.env.X === 'string' — يجب أن تكون القيمة موجودة.

Question 7

ربط النطاق المخصّص (Custom Domain)

Accepted Answer

العرض: بعد إضافة النطاق يظهر Domain not verified، أو الرابط يعرض شهادة SSL غير صالحة.

السبب: سجلّات DNS ناقصة أو تشير لجهة خاطئة، أو النطاق أُضيف قبل النشر الأوّل للمشروع.

التشخيص: انشر المشروع أوّلًا للحصول على رابط lovable.app. — افتح لوحة DNS لدى المسجّل وتحقّق من سجلّات CNAME/A كما تعرضها Lovable. — انتظر انتشار DNS (قد يستغرق حتى 24 ساعة) واختبر عبر dig أو nslookup.

الحلّ: أضف سجلّات DNS كما تعرضها إعدادات النطاق في Lovable بالضبط، ثم اضغط Verify. الشهادة تُصدر تلقائيًا بعد التحقّق.

التحقّق: افتح النطاق في نافذة خاصّة — يجب أن يفتح موقعك مع قفل SSL أخضر.

Question 8

تعارض مع GitHub (Merge conflicts)

Accepted Answer

العرض: المزامنة مع GitHub تفشل مع رسالة conflict، أو التغييرات لا تظهر بعد الدفع.

السبب: تعديل نفس الملفّات محلّيًا وعلى Lovable في نفس الوقت، أو فرع رئيسي مختلف بين الطرفين.

التشخيص: افتح GitHub وراجع الفرع الذي يزامنه Lovable (main افتراضيًا). — افحص قائمة الملفّات المتعارضة في رسالة الخطأ. — تحقّق أنّه لا يوجد Pull Request مفتوح لم يُدمج.

الحلّ: احلّ التعارض في GitHub (اختر النسخة الصحيحة أو ادمجها يدويًا)، ادفع إلى main، ثمّ اضغط Pull في Lovable لسحب النسخة الموحّدة.

التحقّق: ملفّ package.json و src/routeTree.gen.ts متطابقان بين GitHub وLovable، والمعاينة تعمل دون Build failed.

Question 9

فشل ترحيل قاعدة البيانات (Migration)

Accepted Answer

العرض: SQL migration يفشل مع relation already exists، أو column does not exist، أو permission denied for schema public.

السبب: تعارض بين هجرات سابقة ولاحقة، أو إنشاء جدول بلا GRANT، أو محاولة تعديل schema محميّ مثل auth/storage.

التشخيص: افحص رسالة الخطأ وحدّد اسم الجدول/العمود المتعارض. — استخدم IF NOT EXISTS و IF EXISTS في العبارات القابلة للتكرار. — تأكّد أنّ الهجرة تعمل فقط على schema public.

الحلّ: أضف IF NOT EXISTS، اكتب هجرة عكسيّة تصلح الحالة، ولا تعدّل أبدًا schemas: auth/storage/realtime. أضف GRANT لكل جدول جديد.

التحقّق: أعد تشغيل الهجرة — يجب أن تنجح بلا خطأ، ويظهر الجدول في Database → Tables مع سياسات RLS.

Question 10

مشاكل RTL على الهاتف

Accepted Answer

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

السبب: استخدام left/right بدلًا من الخصائص المنطقيّة (start/end)، أو غياب dir="rtl" على العنصر الجذر، أو ثبات اتّجاه المكوّنات المستوردة.

التشخيص: افتح Inspector في الهاتف وتحقّق أنّ <html dir="rtl" lang="ar">. — ابحث عن أيّ class يستخدم ml-/mr-/left-/right- بدلًا من ms-/me-/start-/end-. — اختبر على عرض 375px بالضبط.

الحلّ: اضبط dir="rtl" على html في __root.tsx، واستبدل كل ml-/mr-/left-/right- بـ ms-/me-/start-/end- في Tailwind.

التحقّق: على عرض 375px: النصّ من اليمين، الأيقونات في الجهة الصحيحة، ولا يوجد أفقي scroll.

Question 11

نفاد الرصيد (Credits)

Accepted Answer

العرض: الشات يرفض تنفيذ الأوامر مع رسالة You've run out of credits أو Insufficient credits.

السبب: استهلاك رصيد الخطة الشهري قبل نهاية الدورة، أو استخدام كثيف لـ Chat/Build في مشروع واحد.

التشخيص: افتح Workspace Settings → Usage وراجع الاستهلاك المتبقّي. — قيّم إن كانت الرسائل الطويلة/التصحيحات المتكرّرة ترفع الاستهلاك. — افصل بين Chat Mode (أرخص) وBuild Mode للأسئلة النظريّة.

الحلّ: استخدم Chat Mode للأسئلة دون تعديل الكود، اكتب برومبتات محدّدة قصيرة، وارفع الخطّة إن كان المشروع تجاريًا. الرصيد يتجدّد بداية كل دورة.

التحقّق: لوحة Usage تُظهر رصيدًا كافيًا، ورسائل جديدة تُنفَّذ بلا خطأ نفاد.

Question 12

أخطاء Server Functions

Accepted Answer

العرض: استدعاء createServerFn يعيد 500 أو Unauthorized أو ReferenceError رغم نجاح البناء.

السبب: منتصف middleware المصادقة مفقود، قراءة process.env في module scope، أو استيراد ملفّ *.server.ts من مكوّن واجهة.

التشخيص: افتح Server Function Logs وابحث عن أوّل stack trace. — تحقّق أنّ src/start.ts يضمّ attachSupabaseAuth في functionMiddleware للدوالّ المحميّة. — تأكّد أنّ ملفّ createServerFn لا يحتوي على منطق runtime في module scope — فقط الاستيرادات والدالّة المصدّرة.

الحلّ: انقل كل helper إلى ملفّ منفصل، اقرأ الأسرار داخل .handler() فقط، وأضف middleware المصادقة عند الحاجة. لا تستدعِ Server Functions محميّة من مسار عام.

التحقّق: استدعاء الدالّة من الواجهة يعيد 200 والبيانات المتوقّعة، وسجلّ Logs يُظهر تنفيذًا ناجحًا.

Question 13

خطأ Hydration mismatch

Accepted Answer

العرض: يظهر تحذير React في الكونسول: HTML المولّد من الخادم لا يطابق ما بناه العميل بعد التحميل.

السبب: قراءة قيم من localStorage أو cookies داخل مُبادِر useState — القيم غير متوفّرة على الخادم.

الحلّ: انقل القراءة إلى useEffect أو استخدم useHydrated يعيد قيمة افتراضية أثناء SSR.

التحقّق: أعد تحميل الصفحة — لا يظهر تحذير hydration في الكونسول.

Question 14

الويب-هوك يعيد 401 Invalid signature

Accepted Answer

العرض: الحدث يصل من Stripe/Paddle ثم يُرفض بـ 401.

السبب: قراءة body عبر await request.json() تفسد raw body المستخدم للتحقّق من التوقيع.

الحلّ: اقرأ request.text() مرّة واحدة، تحقّق من التوقيع بـ HMAC، ثم JSON.parse على النصّ.

التحقّق: أرسل حدثًا تجريبيًا من لوحة Stripe — يعود 200 ويُسجَّل في Logs.

Question 15

تعارض مسار / (Multiple routes)

Accepted Answer

العرض: البناء يفشل: Multiple routes matching path /.

السبب: ملفّان يدّعيان المسار الجذر — عادة src/routes/index.tsx و src/routes/_app/index.tsx.

الحلّ: احتفظ بـ src/routes/index.tsx فقط واحذف أيّ ملفّ آخر يدّعي /.

Question 16

حلقة تصيير لا نهائية

Accepted Answer

العرض: المكوّن يعيد التصيير آلاف المرّات ويجمّد المتصفّح.

السبب: setState داخل render مباشرة، أو useEffect بمرجع كائن جديد كل مرّة.

الحلّ: انقل setState إلى event handler، ولفّ الكائنات/الدوالّ في useMemo/useCallback.

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

فشل عملية البناء (Build failed)