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 API. Возвращая объект NextResponse, вы можете напрямую управлять куки, устанавливать заголовки, реализовывать перенаправления и переписывать пути.

Полезно знать: Для перенаправлений вы также можете использовать Response.redirect вместо NextResponse.redirect.

Среда выполнения

По умолчанию Middleware использует Edge runtime. Если вы не хотите этого, вы можете использовать полную среду выполнения Node.js для запуска Middleware.

История версий