跳至内容
API 参考next.config.js 选项redirects

redirects

重定向允许您将传入的请求路径重定向到不同的目标路径。

要使用重定向，您可以在 next.config.js 中使用 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 是一个 has 对象 数组，具有 type、key 和 value 属性。
  • missing 是一个 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（没有嵌套路径）

next.config.js
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

next.config.js
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

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

以下字符 (、)、{、}、:、*、+、? 用于正则表达式路径匹配，因此在 source 中用作非特殊值时，必须在它们之前添加 \\ 进行转义。

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

要仅在头部、Cookie 或查询值也与has字段匹配或不与missing字段匹配时才匹配重定向，可以使用。source和所有has项都必须匹配，并且所有missing项都必须不匹配才能应用重定向。

has和missing项可以具有以下字段

  • type: String - 必须是header、cookie、host或query。
  • key: String - 要匹配的所选类型的键。
  • value: String 或 undefined - 要检查的值，如果未定义，则任何值都将匹配。可以使用类似正则表达式的字符串来捕获值的特定部分，例如，如果将值first-(?<paramName>.*)用于first-second，则second将在目标中使用:paramName可用。
next.config.js
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

next.config.js
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加上区域设置前缀，才能正确匹配。

next.config.js
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标头。

其他重定向

版本历史

版本更改
v13.3.0添加了missing。
v10.2.0添加了has。
v9.5.0添加了redirects。