Вопросы-ответы и разбор типичных ошибок в Next.js Middleware

1. Вопросы и ответы

Вопрос 1. Что такое middleware в Next.js и зачем он нужен?

Ответ:
Middleware — это серверная функция, которая выполняется при каждом запросе к вашему приложению до обработки страниц или API. Она позволяет централизованно реализовывать авторизацию, редиректы, валидацию, модификацию заголовков, ограничение доступа и другие "прослойки" между пользователем и приложением.

Вопрос 2. Где должен находиться файл middleware, чтобы он сработал?

Ответ:
Файл называется middleware.ts или middleware.js и обычно располагается в корне проекта или внутри папки src/. Next.js автоматически подхватывает этот файл, если он есть.

Вопрос 3. Как ограничить срабатывание middleware только на определённых маршрутах?

Ответ:
Для этого используется экспорт объекта config и параметра matcher.
Например:

export const config = {
  matcher: ['/dashboard/:path*', '/profile/:path*', '/admin/:path*']
}

Теперь middleware будет срабатывать только на указанных маршрутах.

Вопрос 4. Можно ли использовать React-хуки или обращаться к базе данных в middleware?

Ответ:
Нет. Middleware работает на сервере и не поддерживает React-хуки. Также не рекомендуется делать fetch-запросы или обращаться к базе данных, потому что middleware должен быть максимально быстрым и лёгким. Используйте только куки, заголовки и локальные вычисления.

Вопрос 5. Как корректно получить куки или токен пользователя в middleware?

Ответ:
Доступ к куки осуществляется через request.cookies.get('имя_куки').
Если используется next-auth, предпочтительнее получать и расшифровывать токен через getToken из next-auth/jwt, передавая секрет приложения.

Вопрос 6. Как не попасть в бесконечный редирект при авторизации?

Ответ:
Перед редиректом всегда проверяйте, не находитесь ли уже на целевой странице. Например, не редиректите с /login на /login.

Вопрос 7. Middleware обрабатывает только страницы или все запросы?

Ответ:
По умолчанию — все запросы (страницы, API-роуты, статику и даже картинки). Поэтому важно явно ограничивать область действия middleware через matcher.

2. Разбор типичных ошибок в middleware

Ошибка №1: Middleware применяется ко всему приложению

Проблема:
Если не указать matcher, middleware будет срабатывать на каждый запрос: публичные страницы, картинки, API, статика — всё попадает под обработку.

Чем грозит:
Бесконечные редиректы, невозможность зайти на /login, медленная загрузка приложения.

Как исправить:
Всегда указывайте matcher для защищённых маршрутов и исключайте публичные и статические ресурсы.

Ошибка №2: Проверка только наличия куки

Проблема:
Проверка только факта наличия куки (например, if (!session)) не гарантирует, что токен валидный.
Кука может быть устаревшей или подделанной.

Как исправить:
Используйте расшифровку и проверку токена с помощью специальных библиотек (getToken из next-auth/jwt).

Ошибка №3: Редирект на тот же маршрут

Проблема:
Редирект с /login на /login или на текущий маршрут вызывает бесконечную петлю и "сломает" приложение.

Как исправить:
Проверяйте, что текущий маршрут отличается от целевого, прежде чем делать редирект.

Ошибка №4: Попытка обращаться к базе данных или делать fetch в middleware

Проблема:
Любые внешние сетевые запросы в middleware тормозят всю цепочку обработки запроса. Это приводит к задержкам и может негативно сказаться на производительности.

Как исправить:
В middleware используйте только локальные проверки: куки, заголовки, JWT.

Ошибка №5: Неправильная работа с переменными окружения

Проблема:
Если не передать или указать неправильный secret в функцию расшифровки токена (getToken), все токены будут считаться невалидными — никто не сможет авторизоваться.

Как исправить:
Убедитесь, что переменная окружения (например, NEXTAUTH_SECRET) задана правильно и совпадает во всех частях проекта.

Ошибка №6: Middleware блокирует статику или публичные файлы

Проблема:
Если middleware срабатывает на /public, /favicon.ico, картинки или стили, их загрузка может замедлиться или сломаться.

Как исправить:
Исключайте из matcher пути, ведущие к статике и публичным файлам:

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']
}

Ошибка №7: Middleware блокирует API-роуты

Проблема:
Если middleware проверяет авторизацию на /api/* и возвращает редирект, ваши API-эндпоинты станут недоступны.

Как исправить:
Исключайте /api из matcher или добавляйте отдельную логику пропуска для API-запросов внутри middleware.