logoNext.js Русский
ДокументацияБлогИзучение
Введение/Справочник API/Функции/NextRequest и NextResponse

NextRequest и NextResponse

next/server предоставляет серверные помощники для использования в Middleware и Edge API Routes.

NextRequest

Объект NextRequest расширяет нативный интерфейс Request со следующими дополнительными методами и свойствами:

  • cookies - Экземпляр RequestCookies с куками из Request. Читает/изменяет заголовок Cookie запроса. См. также Использование кук в Middleware.

    • get - Метод, принимающий имя куки name и возвращающий объект с name и value. Если кука с name не найдена, возвращает undefined. При нескольких совпадениях возвращает только первое.
    • getAll - Аналогичен get, но возвращает список всех кук с совпадающим name. Если name не указан, возвращает все доступные куки.
    • set - Метод, принимающий объект со свойствами CookieListItem, как определено в спецификации W3C CookieStore API.
    • delete - Метод, принимающий имя куки name или список имен и удаляющий соответствующие куки. Возвращает true для удаленных и false для неудаленных кук.
    • has - Метод, принимающий имя куки name и возвращающий boolean в зависимости от наличия куки (true) или отсутствия (false).
    • clear - Метод без аргументов, который полностью удаляет заголовок Cookie.

  • nextUrl: Включает расширенный, разобранный URL-объект с доступом к специфичным для Next.js свойствам, таким как pathname, basePath, trailingSlash и i18n. Содержит следующие свойства:

    • basePath (string)
    • buildId (string || undefined)
    • defaultLocale (string || undefined)
    • domainLocale
      • defaultLocale: (string)
      • domain: (string)
      • http: (boolean || undefined)
      • locales: (string[] || undefined)
    • locale (string || undefined)
    • url (URL)

  • ip: (string || undefined) - Содержит IP-адрес Request. Эта информация предоставляется хостинг-платформой.

  • geo - Содержит географическое местоположение из Request. Эта информация предоставляется хостинг-платформой. Включает свойства:

    • city (string || undefined)
    • country (string || undefined)
    • region (string || undefined)
    • latitude (string || undefined)
    • longitude (string || undefined)

Вы можете использовать объект NextRequest как прямую замену нативного интерфейса Request, получая больше контроля над манипуляциями с запросом.

NextRequest можно импортировать из next/server:

import type { NextRequest } from 'next/server'

NextFetchEvent

Объект NextFetchEvent расширяет нативный FetchEvent и включает метод waitUntil().

Метод waitUntil() можно использовать для продления выполнения функции, если у вас есть фоновая работа.

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

export function middleware(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  )

  return NextResponse.next()
}

Объект NextFetchEvent можно импортировать из next/server:

import type { NextFetchEvent } from 'next/server'

NextResponse

Класс NextResponse расширяет нативный интерфейс Response следующим:

Публичные методы

Публичные методы доступны на экземпляре класса NextResponse. В зависимости от случая использования вы можете создать экземпляр и получить доступ к следующим методам:

  • cookies - Экземпляр ResponseCookies с куками из Response. Читает/изменяет заголовок Set-Cookie ответа. См. также Использование кук в Middleware.
    • get - Метод, принимающий имя куки name и возвращающий объект с name и value. Если кука с name не найдена, возвращает undefined. При нескольких совпадениях возвращает только первое.
    • getAll - Аналогичен get, но возвращает список всех кук с совпадающим name. Если name не указан, возвращает все доступные куки.
    • set - Метод, принимающий объект со свойствами CookieListItem, как определено в спецификации W3C CookieStore API.
    • delete - Метод, принимающий имя куки name или список имен и удаляющий соответствующие куки. Возвращает true для удаленных и false для неудаленных кук.

Статические методы

Следующие статические методы доступны непосредственно на классе NextResponse:

  • redirect() - Возвращает NextResponse с установленным редиректом
  • rewrite() - Возвращает NextResponse с установленным перезаписыванием
  • next() - Возвращает NextResponse, который продолжает цепочку middleware

Для использования методов выше необходимо возвращать объект NextResponse. NextResponse можно импортировать из next/server:

import { NextResponse } from 'next/server'

userAgent

Помощник userAgent позволяет взаимодействовать с объектом user agent из запроса. Он абстрагирован от нативного объекта Request и является опциональной функцией. Имеет следующие свойства:

  • isBot: (boolean) Указывает, приходит ли запрос от известного бота
  • browser
    • name: (string || undefined) Название браузера
    • version: (string || undefined) Версия браузера, определяется динамически
  • device
    • model: (string || undefined) Модель устройства, определяется динамически
    • type: (string || undefined) Тип браузера, может быть одним из: console, mobile, tablet, smarttv, wearable, embedded или undefined
    • vendor: (string || undefined) Производитель устройства, определяется динамически
  • engine
    • name: (string || undefined) Название движка браузера, может быть: Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, Links, Lynx, NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit или undefined
    • version: (string || undefined) Версия движка браузера, определяется динамически или undefined
  • os
    • name: (string || undefined) Название ОС, может быть undefined
    • version: (string || undefined) Версия ОС, определяется динамически или undefined
  • cpu
    • architecture: (string || undefined) Архитектура CPU, может быть: 68k, amd64, arm, arm64, armhf, avr, ia32, ia64, irix, irix64, mips, mips64, pa-risc, ppc, sparc, sparc64 или undefined

userAgent можно импортировать из next/server:

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

export function middleware(request: NextRequest) {
  const url = request.nextUrl
  const { device } = userAgent(request)
  const viewport = device.type === 'mobile' ? 'mobile' : 'desktop'
  url.searchParams.set('viewport', viewport)
  return NextResponse.rewrite(url)
}

Часто задаваемые вопросы

Почему redirect использует 307 и 308?

При использовании redirect() вы можете заметить, что используются статус-коды 307 для временного редиректа и 308 для постоянного. Традиционно 302 использовался для временного редиректа, а 301 для постоянного, но многие браузеры изменяли метод запроса с POST на GET при использовании 302, независимо от исходного метода запроса.

Рассмотрим пример редиректа с /users на /people: если сделать POST запрос на /users для создания нового пользователя и получить 302 временный редирект, метод запроса изменится с POST на GET. Это не имеет смысла, так как для создания пользователя должен использоваться POST запрос на /people, а не GET.

Введение статус-кода 307 означает, что метод запроса сохраняется как POST.

  • 302 - Временный редирект, изменяет метод запроса с POST на GET
  • 307 - Временный редирект, сохраняет метод запроса как POST

Метод redirect() по умолчанию использует 307 вместо 302, что означает сохранение метода запроса как POST.

Если нужно вызвать GET ответ на POST запрос, используйте 303.

Подробнее о HTTP редиректах.

Как получить доступ к переменным окружения?

process.env можно использовать для доступа к переменным окружения из Edge Middleware. Они вычисляются во время next build:

РаботаетНе работает
console.log(process.env.MY_ENV_VARIABLE)const getEnv = name => process.env[name]
const { MY_ENV_VARIABLE } = process.env
const { "MY-ENV-VARIABLE": MY_ENV_VARIABLE } = process.env

getStaticProps

Справочник API для `getStaticProps`. Узнайте, как использовать `getStaticProps` для генерации статических страниц в Next.js.

useAmp

Включение AMP на странице и управление способом добавления AMP в Next.js с помощью конфигурации AMP.