لما تفتح منتجك وتطلع رسالة مثل Hydration failed because the initial UI does not match what was rendered on the server، أو في نسخ Next.js الأحدث Hydration failed because the server rendered HTML didn't match the client، فهذا خطأ يخص المواقع المبنية بـ Next.js، وهو اللي يستخدمه v0 دايم، وكثير من المنتجات المبنية في Cursor و Bolt. معناه باختصار: الصفحة اللي جهّزها السيرفر غير الصفحة اللي رسمها المتصفح بعده.
إيش يعني بالضبط
Next.js يجهّز الصفحة على السيرفر ويرسلها جاهزة، عشان تفتح بسرعة ومحركات البحث تقرأها. بعدها React في المتصفح يمر على نفس الصفحة ويربط فيها الأزرار والتفاعل. هذي الخطوة اسمها hydration. React يتوقع إن اللي يرسمه في المتصفح يطابق اللي وصل من السيرفر حرف بحرف. إذا لقى فرق، يطلع الخطأ، وأحيانًا يرمي الجزء كله ويرسمه من جديد في المتصفح.
النتيجة اللي تشوفها: وميض في الصفحة، أو نص يتغيّر قدام عينك، أو زر ما يستجيب أول ثواني، أو صفحة بيضاء في الحالات الأسوأ.
في النسخة المنشورة يطلع بشكل ثاني
في وضع التطوير، Next.js يعرض لك نافذة فيها الفرق بالضبط. في النسخة المنشورة، الرسالة تنضغط وتصير شيء مثل Minified React error #418. في React 18 ممكن تجي معها #423 أو #425، وكلها من نفس العائلة: عدم تطابق بين السيرفر والمتصفح. في React 19، اللي يستخدمه Next.js 15 وما بعده، عدم التطابق يطلع #418 فقط. فإذا شفت #418 في Console عند عميل، لا تدوّر على مشكلة ثانية.
ليش يصير كثير في المنتجات المبنية بالذكاء الاصطناعي
الذكاء الاصطناعي يكتب كود يشتغل لما يجرّبه في المعاينة، وما يفكر وين ينفّذ كل سطر: على السيرفر ولا في المتصفح. الأسباب اللي نشوفها أكثر شيء:
- التاريخ والوقت. سطر مثل
new Date().toLocaleDateString()يطلع نتيجة على السيرفر، اللي غالبًا على توقيت UTC وبالإنجليزي، ونتيجة ثانية في جوال عميلك على توقيت الرياض وبالعربي. وحتى لو ثبّت اللغة، فرق الثلاث ساعات يغيّر التاريخ نفسه من 12 بالليل حتى 3 الفجر بتوقيت الرياض. - قيم عشوائية.
Math.random()أو معرّف يتولّد وقت الرسم يعطي قيمة على السيرفر وقيمة ثانية في المتصفح. - أشياء موجودة في المتصفح فقط. كود يقرأ
localStorageأوwindowعشان يقرّر إيش يعرض، مثل الوضع الليلي أو اسم المستخدم المحفوظ. السيرفر ما عنده هالأشياء، فيعرض نسخة، والمتصفح يعرض نسخة ثانية. - HTML غير صحيح.
<div>داخل<p>، أو رابط داخل رابط. المتصفح يعيد ترتيبها بطريقته، فتختلف عن اللي أرسله السيرفر. - إضافات المتصفح. إضافات مثل الترجمة التلقائية أو مدقق الكتابة تعدّل الصفحة قبل ما يوصل لها React. هذا يصير عند بعض الزوار فقط، وما يكون خطأ في كودك.
كيف تتأكد بنفسك
- افتح الصفحة في نافذة خاصة (Incognito) بدون إضافات. إذا الخطأ اختفى، السبب غالبًا إضافة في متصفحك، مو منتجك.
- شغّل المنتج في وضع التطوير (
npm run dev) وافتح نفس الصفحة: نافذة الأخطاء، أو علامة Next.js في زاوية الصفحة في النسخ الأحدث، تعرض الجزء اللي يختلف بين السيرفر والمتصفح. - في النسخة المنشورة، اضغط F12 وافتح تبويب Console: إذا شفت
#418(أو#425في React 18)، دوّر في الصفحة على أي تاريخ أو وقت أو رقم عشوائي أو شيء يعتمد على المستخدم. - غيّر توقيت جهازك وافتح الصفحة: إذا تغيّر نص فيها، هذا مكان المشكلة.
الحل الصح
الفكرة وحدة في كل الحالات: أول رسمة في المتصفح لازم تطابق السيرفر، وبعدها تقدر تغيّر اللي تبيه.
- التاريخ والوقت: ثبّت المنطقة الزمنية في الكود، مثل
timeZone: 'Asia/Riyadh'، أو اعرض الوقت بعد ما تفتح الصفحة في المتصفح. - الأشياء اللي في المتصفح فقط: اقرأها داخل
useEffect، أو حمّل هذا الجزء بالذات في المتصفح فقط عن طريقdynamicمعssr: false. - HTML غير صحيح: صلّح الترتيب. النافذة في وضع التطوير غالبًا تسمّي العنصر.
الحل اللي لا تسويه
أدوات الذكاء الاصطناعي تقترح كثير حلّين سريعين:
- إضافة suppressHydrationWarning على كل شيء. هذي الخاصية موجودة لحالة وحدة صغيرة، مثل وقت يتغيّر بطبيعته، وتشتغل على عنصر واحد فقط. نشرها في كل مكان يخفي الرسالة ويخلّي الفرق نفسه موجود.
- إلغاء الرسم على السيرفر للتطبيق كامل. الخطأ يختفي، لكن الصفحة تفتح أبطأ، ومحركات البحث تشوف صفحة شبه فاضية. يعني تخسر سبب استخدام Next.js من الأساس.
إذا ما لقيت السبب
إذا الخطأ يطلع في صفحة مهمة مثل الدفع أو لوحة العميل، خلّ مهندس يشوفه معك في مكالمة استشارية: نوصل للجزء اللي يختلف ونكتب لك الحل. إذا منتجك من v0، شوف بعد مشاكل v0 الأشهر، وإذا المشكلة بدأت بعد النشر فقط، شوف يشتغل عندك ثم يتعطّل بعد النشر؟.