ملف middleware.js

يُستخدم ملف middleware.js|ts لكتابة الوسيط (Middleware) وتشغيل الكود على الخادم قبل اكتمال الطلب. ثم بناءً على الطلب الوارد، يمكنك تعديل الاستجابة عن طريق إعادة الكتابة، إعادة التوجيه، تعديل رؤوس الطلب أو الاستجابة، أو الرد مباشرة.

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

استخدم الملف middleware.ts (أو .js) في جذر مشروعك لتحديد الوسيط. على سبيل المثال، في نفس مستوى app أو pages، أو داخل src إذا كان ذلك ينطبق.

import { NextResponse, NextRequest } from 'next/server'

// يمكن وضع علامة `async` على هذه الدالة إذا كنت تستخدم `await` داخلها
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

import { NextResponse } from 'next/server'

// يمكن وضع علامة `async` على هذه الدالة إذا كنت تستخدم `await` داخلها
export function middleware(request) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

التصديرات

دالة الوسيط (Middleware function)

يجب أن يصدر الملف دالة واحدة، إما كتصدير افتراضي أو مسماة middleware. لاحظ أنه لا يتم دعم وسائط متعددة من نفس الملف.

// مثال على التصدير الافتراضي
export default function middleware(request) {
  // منطق الوسيط
}

كائن التكوين (اختياري)

اختياريًا، يمكن تصدير كائن تكوين إلى جانب دالة الوسيط. يتضمن هذا الكائن matcher لتحديد المسارات التي ينطبق عليها الوسيط.

Matcher

يتيح لك خيار matcher استهداف مسارات محددة لتنفيذ الوسيط عليها. يمكنك تحديد هذه المسارات بعدة طرق:

• لمسار واحد: استخدم سلسلة نصية مباشرة لتحديد المسار، مثل '/about'.
• لمسارات متعددة: استخدم مصفوفة لسرد مسارات متعددة، مثل matcher: ['/about', '/contact']، مما يطبق الوسيط على كل من /about و /contact.

بالإضافة إلى ذلك، يدعم matcher مواصفات مسارات معقدة من خلال التعبيرات العادية، مثل matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)']، مما يتيح التحكم الدقيق في المسارات التي يجب تضمينها أو استبعادها.

يقبل خيار matcher أيضًا مصفوفة من الكائنات بالمفاتيح التالية:

• source: المسار أو النمط المستخدم لمطابقة مسارات الطلب. يمكن أن يكون سلسلة لمطابقة المسار مباشرة أو نمطًا لمطابقة أكثر تعقيدًا.
• regexp (اختياري): سلسلة تعبير عادي تضبط المطابقة بناءً على المصدر. توفر تحكمًا إضافيًا في المسارات المشمولة أو المستبعدة.
• locale (اختياري): قيمة منطقية، عند تعيينها إلى false، تتجاهل التوجيه القائم على اللغة في مطابقة المسار.
• has (اختياري): يحدد الشروط بناءً على وجود عناصر طلب محددة مثل الرؤوس، معلمات الاستعلام، أو ملفات تعريف الارتباط.
• missing (اختياري): يركز على الشروط حيث تكون بعض عناصر الطلب غائبة، مثل الرؤوس أو ملفات تعريف الارتباط المفقودة.

export const config = {
  matcher: [
    {
      source: '/api/*',
      regexp: '^/api/(.*)',
      locale: false,
      has: [
        { type: 'header', key: 'Authorization', value: 'Bearer Token' },
        { type: 'query', key: 'userId', value: '123' },
      ],
      missing: [{ type: 'cookie', key: 'session', value: 'active' }],
    },
  ],
}

المعاملات

request

عند تعريف الوسيط، تقبل الدالة الافتراضية المُصدَّرة معاملًا واحدًا، request. هذا المعامل هو نسخة من NextRequest، الذي يمثل طلب HTTP الوارد.

import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // يتم وضع منطق الوسيط هنا
}

export function middleware(request) {
  // يتم وضع منطق الوسيط هنا
}

معلومة مفيدة:

• NextRequest هو نوع يمثل طلبات HTTP الواردة في وسيط Next.js، بينما NextResponse هو فئة تُستخدم لمعالجة وإرسال استجابات HTTP.

NextResponse

يمكن للوسيط استخدام كائن NextResponse الذي يمتد من واجهة برمجة تطبيقات الاستجابة (Web Response API). بإرجاع كائن NextResponse، يمكنك معالجة ملفات تعريف الارتباط مباشرة، تعيين الرؤوس، تنفيذ عمليات إعادة التوجيه، وإعادة كتابة المسارات.

معلومة مفيدة: لإعادة التوجيه، يمكنك أيضًا استخدام Response.redirect بدلاً من NextResponse.redirect.

وقت التشغيل (Runtime)

يستخدم الوسيط Edge runtime افتراضيًا. إذا كنت لا تريد ذلك، يمكنك استخدام Node.js runtime الكامل لتشغيل الوسيط.

سجل الإصدارات