كيف تصلح الصفحة البيضاء الفارغة في تطبيق الويب

الصفحة البيضاء الفارغة تعني غالباً أحد أمرين: إما أن JavaScript في التطبيق تعطّل قبل أن يرسم أي شيء، أو أن JavaScript لم يُحمَّل من الأساس. افتح Console في المتصفح (انقر بالزر الأيمن ← Inspect ← Console) واقرأ أول خطأ أحمر، ثم تحقق من تبويب Network بحثاً عن الملفات التي فشل تحميلها. معظم الأسباب هي متغير بيئة مفقود، أو مسار أساسي خاطئ، أو بناء لم يكتمل، أو عطل في مكوّن واحد.

هذا الدليل يغطي تطبيقات الصفحة الواحدة (SPA) المبنية بـ React أو Vue أو أطر مشابهة، بما في ذلك التطبيقات التي يصنعها منشئو التطبيقات بالذكاء الاصطناعي، وهي البيئة التي تظهر فيها الصفحات البيضاء أكثر من غيرها.

لماذا تكون الصفحة بيضاء

تطبيق الصفحة الواحدة الحديث يرسل إلى المتصفح ملف HTML شبه فارغ، تقريباً بهذا الشكل:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

ثم يبني JavaScript الصفحة كاملةً داخل ذلك الـ div الفارغ. إذا فشل تحميل السكربت، أو ألقى خطأً قبل أن يرسم، يبقى الـ div فارغاً وتظهر لك صفحة بيضاء. الصفحة ليست «معطلة» بشكل ظاهر؛ هي ببساطة لم تُرسم أبداً.

لهذا السبب، يبدأ الإصلاح دائماً من أدوات المطوّر، لا من الصفحة نفسها.

الخطوة 1: اقرأ Console

افتح أدوات المطوّر: انقر بالزر الأيمن على الصفحة واختر Inspect، أو اضغط F12 (أو Cmd+Option+I على Mac). انتقل إلى تبويب Console وأعد تحميل الصفحة.

انظر إلى أول خطأ أحمر؛ الأخطاء اللاحقة غالباً آثار جانبية. ما يقوله يشير إلى السبب:

انسخ نص الخطأ كاملاً، بما فيه اسم الملف ورقم السطر. إذا كنت تستخدم منشئ تطبيقات بالذكاء الاصطناعي، فالصقه مباشرة في الدردشة.

الخطوة 2: تحقق من تحميل الملفات

افتح تبويب Network، وفعّل Disable cache، ثم أعد التحميل. انظر إلى طلبات ملفات .js و.css.

• حالة 404 على ملف JavaScript: الصفحة تطلب ملفاً غير موجود على الخادم.
• حالة 200 لكن النوع text/html: الخادم أعاد صفحة (غالباً index.html نفسه، بسبب قاعدة الرجوع إلى SPA) بدلاً من السكربت. السبب الجذري واحد: الملف ليس حيث تتوقعه الصفحة.

الأسباب الشائعة:

مسار أساسي خاطئ. إذا كان التطبيق يُقدَّم من مجلد فرعي، مثل example.com/app/، لكنه بُني ليحمّل الملفات من /assets/...، فستفشل كل طلبات السكربت. في Vite هذا هو الخيار base في vite.config؛ وفي Create React App هو الحقل homepage؛ وفي Next.js هو basePath. يجب أن يطابق المكان الذي يُقدَّم منه التطبيق فعلياً.

index.html قديم. أدوات البناء تعطي الملفات أسماء تحمل بصمة المحتوى، مثل index-a1b2c3.js. بعد نشر جديد، يختفي الملف القديم. إذا ما زال المتصفح أو شبكة توصيل المحتوى تخزّن index.html القديم، فسيطلب الملف القديم ولن يجد شيئاً. التحديث القوي (Cmd+Shift+R أو Ctrl+Shift+R) يؤكد ذلك. الحل على المدى الطويل أن يُقدَّم index.html مع ترويسة تخزين مؤقت قصيرة أو بدون تخزين، بينما تُخزَّن الملفات ذات البصمة لمدة طويلة.

لم يكتمل البناء أو لم يُنشر. إذا فشل البناء، فقد يقدم المزود مجلد مخرجات قديماً أو فارغاً. تحقق من سجل البناء بحثاً عن الأخطاء.

المجلد الخاطئ منشور. يجب أن يقدم المزود مخرجات البناء (عادةً dist أو build)، لا مجلد المصدر في المشروع. تقديم المصدر يعطيك index.html يشير إلى /src/main.tsx، والمتصفح لا يستطيع تشغيله.

الخطوة 3: تحقق من متغيرات البيئة

تطبيقات الواجهة الأمامية كثيراً ما تقرأ إعدادات مثل عنوان الواجهة البرمجية أو مفتاح عام وقت البناء. إذا كان متغير مفقوداً في البناء المنشور، فكود مثل createClient(undefined, undefined) يتعطل فوراً، وتصبح الصفحة بيضاء.

أشياء يجب معرفتها:

• في Vite، المتغيرات التي تبدأ بـ VITE_ فقط متاحة في كود المتصفح، وتُقرأ كـ import.meta.env.VITE_NAME. في Create React App البادئة هي REACT_APP_؛ وفي Next.js هي NEXT_PUBLIC_.
• هذه القيم تُضمَّن وقت بناء التطبيق. إضافة متغير بعد البناء لا تفعل شيئاً حتى تعيد البناء وتعيد النشر.
• المعاينة أو جهازك المحلي قد يملك ملف .env لا يملكه بناء الإنتاج. اضبط المتغيرات نفسها على المزود.
• كل ما يحمل هذه البادئات ينتهي في JavaScript عام. ضع فيها قيماً عامة فقط، ولا تضع أبداً مفاتيح سرية.

اختبار سريع: ابحث في نص خطأ Console عن undefined بجوار اسم إعداد، أو اسأل:

الصفحة المنشورة تعرض صفحة فارغة. اذكر كل متغير بيئة تقرؤه الواجهة الأمامية، وتحقق من أيها مفقود أو فارغ في النسخة الحية، واجعل التطبيق يعرض رسالة خطأ واضحة بدلاً من صفحة فارغة عند غياب أي منها.

الخطوة 4: أصلح العطل

إذا أظهر Console خطأ JavaScript عادياً، فالكود تعطّل أثناء العرض. الأسباب الشائعة في التطبيقات المبنية بالذكاء الاصطناعي:

• بيانات لم تُحمَّل بعد. مكوّن يقرأ user.name قبل أن يصل user. الحل حالة تحميل، أو الوصول الاختياري (user?.name).
• بيانات فارغة. حساب جديد ليس له سجلات، والكود يفترض وجود عنصر واحد على الأقل في القائمة.
• شكل بيانات غير متوقع. أعادت واجهة برمجية كائن خطأ بدلاً من القائمة التي يتوقعها الكود.
• استيراد مفقود بعد إعادة تسمية الملف أو نقله.
• استخدام واجهة خاصة بالمتصفح أثناء العرض على الخادم (SSR)، مثل window أو localStorage داخل مكوّن خادم في Next.js.

أعطِ الذكاء الاصطناعي الخطأ كاملاً، والصفحة التي حدث فيها، والحساب الذي كنت مسجلاً به:

صفحة لوحة التحكم فارغة للمستخدمين الجدد. Console: TypeError: Cannot read properties of undefined (reading 'map') في ProjectList.tsx:18. يعمل مع حسابي، لأن لدي مشاريع. أصلحه بحيث يعرض الحساب الفارغ «لا توجد مشاريع بعد»، وتحقق من حساب جديد في المعاينة.

الخطوة 5: أضف حدّ أخطاء

في React، قد يزيل مكوّن واحد معطّل التطبيق كله، ولهذا يسبب خطأ صغير صفحة فارغة تماماً. حدّ الأخطاء (error boundary) مكوّن يلتقط أخطاء العرض الواقعة تحته، ويعرض بدلها رسالة بديلة.

أضف حدّ أخطاء حول المسارات الرئيسية يعرض «حدث خطأ ما» مع زر إعادة التحميل، ويسجّل الخطأ في Console. أبقِ الترويسة والتنقل خارجه حتى يظلا ظاهرين.

هذا لا يصلح العطل، لكن الزوار يرون رسالة بدلاً من شاشة فارغة، وأنت ترى أين حدث الانكسار.

الخطوة 6: لا توجد أخطاء، ومع ذلك الصفحة فارغة

إذا كان Console نظيفاً والسكربتات تُحمَّل:

• تحقق من تبويب Elements. هل يوجد محتوى داخل <div id="root">؟ إذا نعم، فالتطبيق يُرسم لكنه غير مرئي: نص أبيض على أبيض، أو opacity: 0، أو display: none، أو عنصر بملء الشاشة يغطيه.
• تحقق من الموجّه. إذا لم يطابق أي مسار الرابط الحالي، ولم يكن هناك مسار «غير موجود»، فبعض الموجّهات لا تعرض شيئاً. أضف مساراً شاملاً يعرض صفحة 404.
• تحقق من نقطة التركيب (mount point). يجب أن يُركَّب الكود داخل عنصر موجود. إذا كان index.html فيه id="app" والكود يبحث عن root، فلن يظهر شيء (وغالباً يسجّل React خطأً).
• تحقق من إضافة في المتصفح. جرّب نافذة خاصة (private). بعض مانعات الإعلانات تحجب سكربتات بأسماء مثل analytics أو ads.

هل تظهر الصفحة البيضاء فقط بعد تحديث صفحة؟

إذا كانت الصفحة الرئيسية تعمل، لكن تحديث /dashboard يعرض صفحة فارغة أو 404، فالخادم لا يعرف أنه يجب إرسال index.html لمسارات التطبيق. هذه مشكلة في قاعدة الرجوع للتوجيه، وتغطيها كيف تصلح أخطاء 404 بعد النشر.

أخطاء شائعة

• قراءة الخطأ الأخير بدلاً من الأول. السطر الأحمر الأول غالباً هو السبب.
• ضبط متغيرات البيئة دون إعادة البناء. متغيرات الواجهة الأمامية تُثبَّت وقت البناء.
• الاختبار بحسابك أنت فقط. أعطال الحسابات الفارغة من أكثر أسباب الصفحات البيضاء شيوعاً.
• افتراض أن النشر نجح. تحقق من سجل البناء قبل تصحيح الكود.
• إلقاء اللوم على ذاكرة المتصفح المؤقتة في كل شيء. التحديث القوي يستبعدها في ثوانٍ؛ إذا بقيت الصفحة فارغة، فالسبب شيء آخر.

الصفحات البيضاء في Mythex

إذا كانت المعاينة فارغة، فتحقق أولاً من أن التطبيق يعمل (افتح Code ← terminal)، ثم اطلب من Mythex تشغيل الخادم الصحيح، أو انقر Refresh في شريط أدوات المعاينة، أو استخدم /fix. أما إذا كان الرابط المنشور فارغاً، فتقترح الوثائق الانتظار دقيقة والتحديث القوي، والتأكد من ضبط متغيرات البيئة وقاعدة البيانات قبل النشر، والتحقق من حصة الاستضافة. تذكّر أن التطبيق المنشور نسخة لقطة: بعد أي إصلاح، انشر مرة أخرى. وإذا كان التغيير هو السبب، فاستخدم Revert to this point في آخر رد سليم لاستعادة المشروع. راجع استكشاف الأخطاء واستكشاف أخطاء النشر في الوثائق، ودليلنا العام عن تصحيح تطبيق بُني بالذكاء الاصطناعي.

قائمة مراجعة الصفحة البيضاء

• قرأت أول خطأ أحمر في Console
• تحققت من تبويب Network بحثاً عن ملفات .js و.css التي تعطي 404 أو تعيد HTML
• المسار الأساسي يطابق المكان الذي يُقدَّم منه التطبيق
• اكتمل البناء، والمجلد الذي يُنشر هو مخرجات البناء
• كل متغيرات البيئة للواجهة الأمامية مضبوطة في البناء المنشور، ثم أُعيد البناء
• العطل مُصلَح، بما في ذلك للحسابات الفارغة والجديدة
• حدّ أخطاء موجود، فتظهر رسالة بدلاً من الصفحة الفارغة مستقبلاً
• مسار شامل للروابط غير المعروفة
• اختبرت بعد تحديث قوي، وفي نافذة خاصة

الأسئلة