Перенаправления

Перенаправления позволяют перенаправлять входящий путь запроса на другой путь назначения.

Для использования перенаправлений можно использовать ключ redirects в next.config.js.

module.exports = {
  async redirects() {
    return [
      {
        source: '/about',
        destination: '/',
        permanent: true,
      },
    ]
  },
}

redirects — это асинхронная функция, которая ожидает возврата массива, содержащего объекты с source, destination, и permanent свойствами:

• source — шаблон входящего пути запроса.
• destination — путь, на который нужно перенаправить.
• permanent true или false - если true, будет использоваться код состояния 308, который инструктирует клиентов/поисковые системы кэш перенаправление навсегда; если false, будет использоваться код состояния 307, который является временным и не кэшируется.

Почему Next.js использует 307 и 308? Традиционно для временного перенаправления использовался код 302, а для постоянного — 301. Однако многие браузеры изменяли метод запроса перенаправления на GET, независимо от исходного метода. Например, если браузер отправил запрос на POST /v1/users, который вернул код состояния 302 с местоположением /v2/users, последующий запрос мог быть GET /v2/users вместо ожидаемого POST /v2/users. Next.js использует коды состояния временного перенаправления 307 и постоянного перенаправления 308 для явного сохранения метода запроса, который использовался.

• basePath: false или undefined - если false, basePath не будет включено при сопоставлении, может использоваться только для внешних перенаправлений.
• locale: false или undefined - нужно ли не включать локаль при сопоставлении.
• has — массив объектов со свойствами type, key и value.
• missing — массив отсутствующих объектов со свойствами type, key и value.

Перенаправления проверяются до системы файлов, которая включает страницы и /public файлы.

При использовании маршрутизатора страниц перенаправления не применяются к клиентской маршрутизации (Link, router.push) , если нет Средств-посредников , которые соответствуют пути.

При применении перенаправления любые значения запроса, предоставленные в запросе, будут переданы в пункт назначения перенаправления. Например, рассмотрите следующую конфигурацию перенаправления:

{
  source: '/old-blog/:path*',
  destination: '/blog/:path*',
  permanent: false
}

Когда запрашивается /old-blog/post-1?hello=world, клиент будет перенаправлен на /blog/post-1?hello=world.

Сопоставление путей

Допускается соответствие путей, например, /old-blog/:slug будет соответствовать /old-blog/hello-world (без вложенных путей):

module.exports = {
  async redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/news/:slug', // Matched parameters can be used in the destination
        permanent: true,
      },
    ]
  },
}

Сопоставление путей с подстановкой

Для сопоставления пути с подстановкой можно использовать * после параметра, например, /blog/:slug* будет соответствовать /blog/a/b/c/d/hello-world:

module.exports = {
  async redirects() {
    return [
      {
        source: '/blog/:slug*',
        destination: '/news/:slug*', // Matched parameters can be used in the destination
        permanent: true,
      },
    ]
  },
}

Сопоставление путей по регулярному выражению

Для сопоставления пути по регулярному выражению можно заключить регулярное выражение в скобки после параметра, например /post/:slug(\\d{1,}) будет соответствовать /post/123, но не /post/abc:

module.exports = {
  async redirects() {
    return [
      {
        source: '/post/:slug(\\d{1,})',
        destination: '/news/:slug', // Matched parameters can be used in the destination
        permanent: false,
      },
    ]
  },
}

Следующие символы (, ), {, }, :, *, +, ? используются для сопоставления путей по регулярным выражениям, поэтому при использовании в source в качестве неспециальных значений они должны быть экранированы добавлением \\ перед ними:

module.exports = {
  async redirects() {
    return [
      {
        // this will match `/english(default)/something` being requested
        source: '/english\\(default\\)/:slug',
        destination: '/en-us/:slug',
        permanent: false,
      },
    ]
  },
}

Сопоставление заголовков, куки и параметров запроса

Чтобы перенаправление срабатывало только при совпадении значений заголовков, куки или параметров запроса с полем has или при их несовпадении с полем missing, можно использовать. Как поля source, так и все элементы has должны соответствовать, а все элементы missing не должны соответствовать, чтобы перенаправление было применено.

Элементы has и missing могут иметь следующие поля:

• type: String - должно быть либо header, cookie, host, или query.
• key: String - ключ из выбранного типа для сопоставления.
• value: String или undefined - значение для проверки, если undefined, любое значение будет соответствовать. Можно использовать регулярное выражение, например, строку для захвата конкретной части значения. Например, если для first-second используется значение first-(?<paramName>.*), то second можно использовать в пункте назначения с :paramName.

module.exports = {
  async redirects() {
    return [
      // if the header `x-redirect-me` is present,
      // this redirect will be applied
      {
        source: '/:path((?!another-page$).*)',
        has: [
          {
            type: 'header',
            key: 'x-redirect-me',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // if the header `x-dont-redirect` is present,
      // this redirect will NOT be applied
      {
        source: '/:path((?!another-page$).*)',
        missing: [
          {
            type: 'header',
            key: 'x-do-not-redirect',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // if the source, query, and cookie are matched,
      // this redirect will be applied
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // the page value will not be available in the
            // destination since value is provided and doesn't
            // use a named capture group e.g. (?<page>home)
            value: 'home',
          },
          {
            type: 'cookie',
            key: 'authorized',
            value: 'true',
          },
        ],
        permanent: false,
        destination: '/another/:path*',
      },
      // if the header `x-authorized` is present and
      // contains a matching value, this redirect will be applied
      {
        source: '/',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        permanent: false,
        destination: '/home?authorized=:authorized',
      },
      // if the host is `example.com`,
      // this redirect will be applied
      {
        source: '/:path((?!another-page$).*)',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
    ]
  },
}

Перенаправления с поддержкой basePath

При использовании basePath поддержки с перенаправлениями каждый source и destination автоматически предваряется basePath, если вы не добавили basePath: false в перенаправление:

module.exports = {
  basePath: '/docs',
 
  async redirects() {
    return [
      {
        source: '/with-basePath', // automatically becomes /docs/with-basePath
        destination: '/another', // automatically becomes /docs/another
        permanent: false,
      },
      {
        // does not add /docs since basePath: false is set
        source: '/without-basePath',
        destination: 'https://example.com',
        basePath: false,
        permanent: false,
      },
    ]
  },
}

Перенаправления с поддержкой i18n

При использовании i18n поддержки с перенаправлениями каждый source и destination автоматически предваряется для обработки настроенной locales, если вы не добавили locale: false в перенаправление. Если используется locale: false, необходимо добавить префикс source и destination с локалью, чтобы оно правильно соответствовало.

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },
 
  async redirects() {
    return [
      {
        source: '/with-locale', // automatically handles all locales
        destination: '/another', // automatically passes the locale on
        permanent: false,
      },
      {
        // does not handle locales automatically since locale: false is set
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
        permanent: false,
      },
      {
        // this matches '/' since `en` is the defaultLocale
        source: '/en',
        destination: '/en/another',
        locale: false,
        permanent: false,
      },
      // it's possible to match all locales even when locale: false is set
      {
        source: '/:locale/page',
        destination: '/en/newpage',
        permanent: false,
        locale: false,
      },
      {
        // this gets converted to /(en|fr|de)/(.*) so will not match the top-level
        // `/` or `/fr` routes like /:path* would
        source: '/(.*)',
        destination: '/another',
        permanent: false,
      },
    ]
  },
}

В некоторых редких случаях может потребоваться назначить пользовательский код состояния для более старых HTTP-клиентов, чтобы обеспечить правильное перенаправление. В таких случаях можно использовать свойство statusCode вместо свойства permanent, но не оба. Для обеспечения совместимости с IE11 для кода состояния 308 автоматически добавляется заголовок Refresh.

Другие перенаправления

• Внутри Маршрутах API и Обработчиках маршрутов вы можете перенаправлять на основе входящего запроса.
• Внутри getStaticProps и getServerSideProps вы можете перенаправлять определенные страницы во время запроса.

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