Lorixen.
AR

صفحة بيضاء بعد كل تحديث للوحة: خطأ تحميل الأجزاء في Vite

باختصار: إذا كان موظفو الاستقبال أو المبيعات يتركون لوحة الحجز أو الطلبات مفتوحة طوال اليوم، ثم بعد كل تحديث ينشره المطور تظهر لهم صفحة بيضاء أو رسالة مثل «Failed to fetch dynamically imported module» أو ChunkLoadError عند فتح قسم جديد، فالسبب أن الصفحة المفتوحة عندهم ما زالت تطلب ملفات من النسخة القديمة، وهذه الملفات حُذفت مع النشر الجديد. توثيق Vite يشرح هذه الحالة بالتحديد، ويقترح ثلاثة أمور: الاستماع لحدث vite:preloadError لإعادة تحميل الصفحة، وضبط Cache-Control: no-cache على ملف HTML، والانتباه إلى أن خدمة الاستضافة قد تحذف ملفات النشرات السابقة.

المشهد في مكتب حقيقي

شركة سياحة في عمّان لديها لوحة داخلية مبنية بـ React وVite لإدارة الحجوزات. الموظفون يفتحونها صباحاً ولا يغلقونها. في منتصف النهار، نشر المطور تحديثاً صغيراً لصفحة التقارير. بعدها بدقائق، بدأ الموظفون يشتكون: الضغط على «التقارير» أو «الفواتير» يُظهر صفحة بيضاء، أو لا يحدث شيء. أحدهم أغلق المتصفح وفتحه من جديد، فعادت اللوحة تعمل.

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

لماذا يحدث هذا؟

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

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

بلغة بسيطة: صفحة الموظف ما زالت «تتذكر» أسماء ملفات الأمس، والخادم لم يعد يملكها.

كيف تعرف أن هذه هي المشكلة؟

قبل أن يبحث المطور في الكود الجديد، اجمع هذه المعلومات من الموظفين:

  • هل ظهرت المشكلة بعد نشر تحديث مباشرة؟
  • هل كانت الصفحة مفتوحة من قبل النشر؟
  • هل تختفي المشكلة بعد تحديث الصفحة أو إغلاق المتصفح؟
  • هل تحدث عند فتح قسم لم يُفتح من قبل في الجلسة نفسها، مثل التقارير؟

إذا كانت الإجابات نعم، فالسبب على الأرجح ملفات النسخة القديمة لا خطأ في الميزة الجديدة. وفي أدوات المطور في المتصفح، يظهر في قائمة الطلبات ملف JavaScript برمز 404، واسمه يحمل بصمة لا توجد في النسخة الحالية على الخادم.

الحل الأول: إعادة تحميل الصفحة عند فشل التحميل

يذكر التوثيق أن Vite يطلق حدثاً اسمه vite:preloadError عندما يفشل في تحميل استيراد ديناميكي، وأن الحدث يحمل الخطأ الأصلي، وأنه إذا استدعيت preventDefault فلن يُرمى الخطأ. ويعرض مثالاً يستمع فيه التطبيق لهذا الحدث ويحدّث الصفحة.

عملياً: عندما يحاول الموظف فتح «التقارير» ويفشل تحميل الجزء القديم، يعيد التطبيق تحميل الصفحة تلقائياً، فيحصل على النسخة الجديدة بملفاتها الجديدة. الموظف يرى وميضاً قصيراً بدل صفحة بيضاء.

نصيحة مهمة للمطور: اجعل إعادة التحميل مرة واحدة فقط لكل جلسة أو لفترة قصيرة. إذا كان الخطأ لسبب آخر، مثل انقطاع الإنترنت، فقد يدخل التطبيق في حلقة إعادة تحميل متكررة. وتذكّر أن أي نموذج نصف مكتوب في الصفحة سيضيع عند إعادة التحميل، فاحفظ المسودات إن أمكن.

الحل الثاني: لا تجعل ملف HTML يُخزن مؤقتاً

التوثيق ينبه بوضوح: في هذه الحالة تأكد من ضبط Cache-Control: no-cache على ملف HTML، وإلا ستبقى الملفات القديمة مُشاراً إليها.

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

اطلب من المطور أو مزود الاستضافة التحقق من ترويسات ملف HTML بعد النشر.

الحل الثالث: احتفظ بالملفات القديمة فترة

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

ناقش مع المطور طريقة النشر المستخدمة: هل تحذف المجلد كله وتضع الجديد؟ أم تضيف الملفات الجديدة بجانب القديمة؟

متصفحات قديمة وحديثة

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

خطة نشر تراعي الموظفين

إلى جانب الحلول التقنية، هذه عادات بسيطة تقلل الإزعاج:

  1. انشر في وقت هادئ: إذا كانت اللوحة تُستخدم بكثافة صباحاً، فالنشر بعد الدوام أفضل.
  2. أبلغ الفريق: رسالة قصيرة في مجموعة العمل: «نزل تحديث، إذا شفتوا صفحة بيضاء اعملوا تحديث للصفحة».
  3. أضف تنبيه «تحديث متاح»: بعض التطبيقات تعرض شريطاً صغيراً يقول إن نسخة جديدة متاحة مع زر تحديث، بدل انتظار الخطأ.
  4. سجّل الأخطاء: إذا كان لديكم نظام تسجيل أخطاء، فراقب هذه الرسالة بعد كل نشر لتعرف هل الحلول تعمل.

هل يؤثر هذا على الزبائن أيضاً؟

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

أسئلة شائعة

شو يعني Failed to fetch dynamically imported module؟

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

ليش بتصلح لما أسكّر المتصفح وأفتحه؟

لأن الصفحة الجديدة تحمّل HTML جديداً يشير إلى ملفات النسخة الجديدة الموجودة فعلاً.

هل إعادة التحميل التلقائي آمنة؟

نعم إذا كانت مرة واحدة. احمِ التطبيق من حلقة إعادة تحميل متكررة، واحفظ المسودات قبلها.

شو دخل Cache-Control بالموضوع؟

إذا خُزّن ملف HTML، يبقى يشير إلى الملفات القديمة. توثيق Vite يوصي بضبط no-cache عليه.

إذا كانت لوحتك أو موقعك يتعطل بعد كل تحديث، راسلنا ونرتب طريقة النشر معك.

المصادر

WhatsAppاحجز مكالمة