يعمل محليًا ويتعطل في الإنتاج؟ دليل عملي لتصحيح أخطاء Next.js

تجنب السبام ومشاكل التسليم. إليك كيفية بناء نموذج اتصال يعمل فعلياً في الإنتاج، باستخدام Turnstile للحماية وResend للتسليم الموثوق.

التطبيق يعمل بشكل ممتاز على localhost، وبعد النشر تظهر صفحة 500.

هذا من أكثر السيناريوهات شيوعًا وإرباكًا في Next.js، خصوصًا مع المسارات المعتمدة على العرض من الخادم في App Router.

الخبر الجيد: هذا النوع من المشاكل غالبًا قابل للتفسير والحل بسرعة، إذا اتبعت منهجًا ثابتًا في التشخيص.

لماذا يحدث "محليًا يعمل / إنتاجيًا يتعطل"؟

الأسباب الأكثر شيوعًا:

1. اختلاف بيئة التشغيل (نسخة Node، اختلاف Runtime بين Node وEdge).
2. اختلاف متغيرات البيئة (متغير ناقص، قيمة خاطئة، Secret بصيغة مختلفة).
3. اختلاف وضع التشغيل (next dev ليس مثل next build && next start).
4. تعطل على مستوى import في أعلى ملف المسار.
5. اختلاف سلوك الشبكة أو الخدمات الخارجية في البنية الإنتاجية.

بدل افتراض أن الخطأ "غامض"، ابدأ بتصنيفه.

الخطوة 1: قِس نطاق العطل عبر فحوص HTTP سريعة

قبل تعديل أي كود، افهم أين الفشل بالضبط:

curl -s -o /dev/null -w '/blog HTTP:%{http_code}\n' 'https://example.com/blog'
curl -s -o /dev/null -w '/blog/known-post HTTP:%{http_code}\n' 'https://example.com/blog/known-post'
curl -s -o /dev/null -w '/blog/missing HTTP:%{http_code}\n' 'https://example.com/blog/definitely-missing-slug'

القراءة العملية:

• صفحة القائمة 200 ومسارات التفاصيل 500 -> الخلل غالبًا في ملف مسار التفاصيل أو مسار العرض.
• slug غير موجود يرجع 500 بدل 404 -> الانهيار يحدث غالبًا قبل وصول التنفيذ إلى notFound().
• الفشل على slug محدد فقط -> احتمال كبير أن المشكلة مرتبطة بالمحتوى أو البيانات.

هذا وحده يختصر وقتًا كبيرًا.

الخطوة 2: أعد الاختبار محليًا في وضع الإنتاج الحقيقي

لا تعتمد على next dev فقط:

npm run dev
npm run build && npm run start

إذا عمل في dev وتعطل في build/start، فالمشكلة غالبًا مرتبطة بـ SSR أو Runtime أو سلوك البناء.

ولرفع دقة التشخيص، طابق بيئة الإنتاج قدر الإمكان:

• نفس نسخة Node (Major)
• نفس متغيرات البيئة
• نفس الإعدادات/الأعلام

الخطوة 3: افحص imports العليا في ملف المسار الفاشل

نقطة مهمة جدًا:
إذا كان import في أعلى ملف المسار يرمي خطأ في الإنتاج، فلن تصل أصلًا إلى try/catch داخل الطلب.

نمط هش:

import HeavyTemplate from "@/components/HeavyTemplate";
import { riskyRender } from "@/lib/risky-renderer";

نمط أكثر أمانًا:

1. أبقِ ملف الدخول للمسار خفيفًا.
2. استخدم lazy import للأجزاء عالية المخاطر.
3. اجعل المسار الاختياري يتحمل الفشل بدل إسقاط الصفحة كلها.

let html: string | undefined;

try {
  const { riskyRender } = await import("@/lib/risky-renderer");
  html = riskyRender(content);
} catch (err) {
  console.error("Optional render path failed:", err);
  html = undefined;
}

الخطوة 4: امنع الانهيار المتسلسل داخل مسار الخطأ

خطأ شائع: داخل catch تستدعي خدمة أخرى غير مستقرة (logger خارجي، SDK مصادقة، إلخ)، فتقع في خطأ ثانٍ ويضيع مسار الإنقاذ.

قواعد مسار الطوارئ:

• أقل اعتماد ممكن على خدمات خارجية
• أقل آثار جانبية ممكنة
• fallback بسيط وموثوق
• slug غير موجود يجب أن ينتهي بـ 404 وليس 500

إذا كان fallback قابلًا للانهيار، فهو ليس fallback.

الخطوة 5: ثبّت اختبارات Smoke بعد كل نشر

بعد كل deploy، شغّل أقل مجموعة ممكنة:

1. صفحة قائمة ثابتة يجب أن تعود 200
2. slug معروف يجب أن يعود 200
3. slug غير موجود مضمون يجب أن يعود 404

سكربت بسيط:

#!/usr/bin/env bash
set -euo pipefail

BASE_URL="${1:-https://example.com}"

curl -s -o /dev/null -w '/blog HTTP:%{http_code}\n' "$BASE_URL/blog"
curl -s -o /dev/null -w '/blog/known-post HTTP:%{http_code}\n' "$BASE_URL/blog/known-post"
curl -s -o /dev/null -w '/blog/missing HTTP:%{http_code}\n' "$BASE_URL/blog/this-post-does-not-exist-xyz-123"

قائمة تحقق سريعة

• هل حددت نمط الفشل عبر HTTP probes أولًا؟
• هل اختبرت في next build && next start؟
• هل طابقت نسخة Node ومتغيرات البيئة مع الإنتاج؟
• هل راجعت imports العليا في ملف المسار الفاشل؟
• هل جعلت المسارات الاختيارية lazy وfault-tolerant؟
• هل مسار fallback بسيط ولا يعتمد على نقاط هشّة؟
• هل أضفت smoke tests بعد النشر؟

الأعطال الإنتاجية ليست ممتعة، لكنها ليست فوضى إذا كانت لديك منهجية واضحة.

حوّل "500 الغامض" إلى خطوات ثابتة، وستتحسن سرعة التشخيص والاسترجاع بشكل كبير.