Переписывания

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

Переписывания действуют как прокси-сервер URL и маскируют целевой путь, создавая впечатление, что пользователь не изменил своё местоположение на сайте. В отличие от этого, перенаправления перенаправят на новую страницу и покажут изменения URL.

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

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

Переписывания применяются к маршрутизации на стороне клиента, переписывание будет применено в приведённом выше примере.

rewrites — это асинхронная функция, которая ожидает возврата массива или объекта массивов (см. ниже), содержащих объекты со свойствами source и destination:

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

Когда функция rewrites возвращает массив, переписывания применяются после проверки файловой системы (страниц и файлов /public) и до динамических маршрутов. Когда функция rewrites возвращает объект массивов со специфической структурой, это поведение можно изменить и более точно контролировать, начиная с v10.1 Next.js:

module.exports = {
  async rewrites() {
    return {
      beforeFiles: [
        // These rewrites are checked after headers/redirects
        // and before all files including _next/public files which
        // allows overriding page files
        {
          source: '/some-page',
          destination: '/somewhere-else',
          has: [{ type: 'query', key: 'overrideMe' }],
        },
      ],
      afterFiles: [
        // These rewrites are checked after pages/public files
        // are checked but before dynamic routes
        {
          source: '/non-existent',
          destination: '/somewhere-else',
        },
      ],
      fallback: [
        // These rewrites are checked after both pages/public files
        // and dynamic routes are checked
        {
          source: '/:path*',
          destination: `https://my-old-site.com/:path*`,
        },
      ],
    }
  },
}

Важно знать: переписывания в beforeFiles не проверяют файловую систему/динамические маршруты сразу после сопоставления источника, они продолжаются до тех пор, пока все beforeFiles не будут проверены.

Порядок проверки маршрутов Next.js:

Проверяются/применяются заголовки.
Проверяются/применяются перенаправления.
Проверяются/применяются переписывания.
Проверяются/отображаются статические файлы из каталога public, файлов _next/static и статических страниц, не являющихся динамическими.
Проверяются/применяются переписывания, если одно из этих переписываний совпадает, мы проверяем динамические маршруты/статические файлы после каждого совпадения.
Проверяются/применяются переписывания, эти переписывания применяются перед рендерингом страницы 404 и после проверки динамических маршрутов/всех статических ресурсов. Если вы используете fallback: true/'blocking' в getStaticPaths, резервный rewrites в вашем next.config.js не будет выполнен.

Параметры переписывания

При использовании параметров в переписывании параметры будут передаваться в запросе по умолчанию, если ни один из параметров не используется в destination.

module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-about/:path*',
        destination: '/about', // The :path parameter isn't used here so will be automatically passed in the query
      },
    ]
  },
}

Если параметр используется в пункте назначения, ни один из параметров не будет автоматически передан в запросе.

module.exports = {
  async rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: '/:path*', // The :path parameter is used here so will not be automatically passed in the query
      },
    ]
  },
}

Вы по-прежнему можете передавать параметры вручную в запросе, если один из них уже используется в пункте назначения, указав запрос в destination.

module.exports = {
  async rewrites() {
    return [
      {
        source: '/:first/:second',
        destination: '/:first?second=:second',
        // Since the :first parameter is used in the destination the :second parameter
        // will not automatically be added in the query although we can manually add it
        // as shown above
      },
    ]
  },
}

Важно знать: Статические страницы из Автоматической статической оптимизации или пререндеринга параметры из переписываний будут обработаны на клиенте после гидратации и предоставлены в запросе.

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

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

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

Сопоставление путей с подстановочными знаками

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

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

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

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

module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-blog/:post(\\d{1,})',
        destination: '/blog/:post', // Matched parameters can be used in the destination
      },
    ]
  },
}

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

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

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

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

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

module.exports = {
  async rewrites() {
    return [
      // if the header `x-rewrite-me` is present,
      // this rewrite will be applied
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // if the header `x-rewrite-me` is not present,
      // this rewrite will be applied
      {
        source: '/:path*',
        missing: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // if the source, query, and cookie are matched,
      // this rewrite 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',
          },
        ],
        destination: '/:path*/home',
      },
      // if the header `x-authorized` is present and
      // contains a matching value, this rewrite will be applied
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        destination: '/home?authorized=:authorized',
      },
      // if the host is `example.com`,
      // this rewrite will be applied
      {
        source: '/:path*',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        destination: '/another-page',
      },
    ]
  },
}

Переписывание на внешний URL

Примеры

Переписывания позволяют переписывать на внешний URL. Это особенно полезно для поэтапного внедрения Next.js. Ниже приведен пример переписывания для перенаправления маршрута /blog вашего основного приложения на внешний сайт.

module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog',
        destination: 'https://example.com/blog',
      },
      {
        source: '/blog/:slug',
        destination: 'https://example.com/blog/:slug', // Matched parameters can be used in the destination
      },
    ]
  },
}

Если вы используете trailingSlash: true, вам также необходимо вставить конечный слэш в параметр source. Если целевой сервер также ожидает конечный слэш, он должен быть включён в параметр destination.

module.exports = {
  trailingSlash: true,
  async rewrites() {
    return [
      {
        source: '/blog/',
        destination: 'https://example.com/blog/',
      },
      {
        source: '/blog/:path*/',
        destination: 'https://example.com/blog/:path*/',
      },
    ]
  },
}

Поэтапное внедрение Next.js

Вы также можете настроить Next.js перенаправлять на существующий веб-сайт после проверки всех маршрутов Next.js.

Таким образом, вам не нужно изменять конфигурацию переписываний при миграции большего количества страниц в Next.js

module.exports = {
  async rewrites() {
    return {
      fallback: [
        {
          source: '/:path*',
          destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*`,
        },
      ],
    }
  },
}