ملف middleware.js

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

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

استخدم ملف middleware.ts (أو .js) في جذر مشروعك لتعريف Middleware. على سبيل المثال، في نفس مستوى مجلد 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

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

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

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

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

Matcher

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

• لمسار واحد: استخدم سلسلة نصية مباشرة لتحديد المسار، مثل '/about'.
• لعدة مسارات: استخدم مصفوفة لسرد عدة مسارات، مثل matcher: ['/about', '/contact']، مما يطبق Middleware على كلا المسارين /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

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

import type { NextRequest } from 'next/server'

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

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

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

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

NextResponse

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

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

وقت التشغيل

يدعم Middleware فقط وقت تشغيل Edge. لا يمكن استخدام وقت تشغيل Node.js.

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