أحصل على أخطاء 404 في لوحة الإدارة بعد النشر
ذاكرة بناء Next.js المؤقتة، خطوات التراجع عن النشر في Railway، إعداد المسارات force-dynamic، والتحديث الكامل للصفحة — تشخيص أخطاء 404 في لوحة إدارة VeloCMS بعد النشر.
دفعت نشرًا جديدًا إلى Railway وأصبحت بعض صفحات الإدارة تعرض 404. المسارات العامة للمدونة تعمل بشكل طبيعي، لكن مسارات الإدارة معطلة. هذا في الغالب مشكلة ذاكرة مؤقتة في Next.js أو توقيت في النشر — لم يُحذف أي شيء فعلًا.
التحديث الكامل للصفحة أولًا
قبل الغوص في سجلات Railway، جرّب تحديثًا كاملًا للصفحة التي تعرض 404. اضغط Ctrl+Shift+R على Windows/Linux أو Cmd+Shift+R على Mac. يُخبر هذا المتصفح بتجاهل ذاكرته المؤقتة من HTML وJavaScript وجلب إصدارات حديثة من الخادم. معظم أخطاء 404 بعد النشر التي تؤثر على متصفحك وحده دون بقية المستخدمين تُحَل بهذه الطريقة.
إذا حلّ التحديث الكامل المشكلة عندك لكن أحد زملائك لا يزال يرى 404، فربما لديه حزمة JavaScript القديمة في الذاكرة المؤقتة. تحمّل مسارات الإدارة قطع JavaScript وفق رمز المحتوى (hash) — بعد النشر، تحمل القطع الجديدة روابط hash جديدة وتُعيد القطع القديمة المخزنة خطأ 404. كلّه يحتاج إلى تحديث كامل أيضًا.
ذاكرة Next.js المؤقتة بعد النشر
تُشغّل عملية البناء في Railway الأمر npm run build الذي يُخرج نتيجة بناء Next.js إلى المجلد .next/. بين عمليات النشر، يحتفظ Railway بطبقة ذاكرة بناء مؤقتة. في حالات نادرة، قد تتعارض ذاكرة جزئية من بناء سابق مع نتيجة البناء الجديد — خاصةً لمسارات الإدارة المُولّدة ديناميكيًا التي تستخدم cookies() أو headers(). تتجلى الأعراض في خطأ 404 على مسارات موجودة بالتأكيد في الكود المصدري.
- انتقل إلى لوحة تحكم Railway ← خدمة VeloCMS ← تبويب عمليات النشر.
- ابحث عن النشر الحالي وانقر على قائمة النقاط الثلاث ← إعادة البناء (وليس إعادة النشر).
- تتجاهل إعادة البناء الذاكرة المؤقتة وتبني من الصفر. يستغرق ذلك من 3 إلى 5 دقائق بدلًا من 1–2 في العادة.
- بعد تفعيل النشر الجديد، اختبر المسار الذي كان يعرض 404 مجددًا.
إعداد المسار force-dynamic بشكل خاطئ
تستخدم مسارات الإدارة في VeloCMS الأمر export const dynamic = 'force-dynamic' لمنع التخزين المؤقت الساكن — إذ يتغير محتوى الإدارة كثيرًا ويجب أن يكون حديثًا دائمًا. إذا كان هذا التوجيه مفقودًا من مسار جديد أضفته، فقد يحاول Next.js تصييره بشكل ساكن أثناء البناء. إن فشل ذلك التصيير الساكن (مثلًا لأنه يحاول قراءة cookies() خلال البناء)، يُسجّل Next.js المسار كإخفاق في التصيير المسبق ويُعيد خطأ 404 وقت التشغيل.
// Every admin page.tsx must include this at the top:
export const dynamic = "force-dynamic";
// Without this, Next.js attempts static generation,
// which fails for pages that read cookies/session.تحقق من أن أي ملفات مسارات إدارة جديدة أضفتها تحتوي على هذا التصدير. يجب وضعه في أعلى ملف page.tsx خارج أي دالة.
خطوات التراجع عن النشر في Railway
إذا كان خطأ 404 يؤثر على جميع مستخدمي الإدارة (وليس متصفحك وحده) وتحتاج إلى استعادة الخدمة فورًا بينما تُشخّص المشكلة، فـ Railway يجعل التراجع أمرًا بسيطًا. انتقل إلى لوحة تحكم Railway ← عمليات النشر ← ابحث عن آخر نشر يعمل ← انقر على ترقية إلى النشط. يجعل هذا النشر السابق حيًّا خلال 30 ثانية دون الحاجة إلى بناء جديد.
التراجع يستعيد الكود السابق لكنه يحتفظ بحالة قاعدة البيانات الحالية. إذا تضمّن النشر الذي أحدث خطأ 404 عملية ترحيل لمخطط PocketBase، فقد يُفضي التراجع عن الكود دون التراجع عن الترحيل إلى تعارض. إذا تضمّن نشرك عمليات ترحيل، فأصلح مشكلة الكود للأمام بدلًا من التراجع.