logoNext.js 简体中文
文档博客学习
简介/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 是由 type、key 和 value 属性组成的 has 对象数组
  • missing 是由 type、key 和 value 属性组成的 missing 对象数组

重定向检查会优先于文件系统（包括页面和 /public 文件）执行。

当使用页面路由时，除非存在 中间件 且匹配路径，否则重定向不会应用于客户端路由（Link、router.push）。

应用重定向时，请求中提供的任何查询值都将传递到重定向目标。例如，参见以下重定向配置：

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

须知：请记住在 source 和 destination 路径参数中的冒号 : 前包含正斜杠 /，否则路径将被视为字面字符串，可能导致无限重定向。

当请求 /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', // 匹配的参数可用于目标路径
        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*', // 匹配的参数可用于目标路径
        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', // 匹配的参数可用于目标路径
        permanent: false,
      },
    ]
  },
}

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

next.config.js
module.exports = {
  async redirects() {
    return [
      {
        // 这将匹配请求 `/english(default)/something`
        source: '/english\\(default\\)/:slug',
        destination: '/en-us/:slug',
        permanent: false,
      },
    ]
  },
}

请求头、Cookie 和查询匹配

要仅在请求头、Cookie 或查询值也匹配 has 字段或不匹配 missing 字段时应用重定向，可以使用这些字段。必须同时匹配 source 和所有 has 项，且所有 missing 项都不匹配才会应用重定向。

has 和 missing 项可包含以下字段：

  • type: String - 必须是 header、cookie、host 或 query 之一
  • key: String - 要匹配的选定类型的键
  • value: String 或 undefined - 要检查的值，如果为 undefined 则匹配任何值。可以使用类似正则表达式的字符串捕获值的特定部分，例如如果对 first-second 使用值 first-(?<paramName>.*)，则可以在目标路径中使用 :paramName 来引用 second
next.config.js
module.exports = {
  async redirects() {
    return [
      // 如果存在 `x-redirect-me` 请求头
      // 将应用此重定向
      {
        source: '/:path((?!another-page$).*)',
        has: [
          {
            type: 'header',
            key: 'x-redirect-me',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // 如果存在 `x-dont-redirect` 请求头
      // 将不应用此重定向
      {
        source: '/:path((?!another-page$).*)',
        missing: [
          {
            type: 'header',
            key: 'x-do-not-redirect',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // 如果匹配源路径、查询和 Cookie
      // 将应用此重定向
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // 由于提供了值且未使用命名捕获组如 (?<page>home)
            // page 值将不会出现在目标路径中
            value: 'home',
          },
          {
            type: 'cookie',
            key: 'authorized',
            value: 'true',
          },
        ],
        permanent: false,
        destination: '/another/:path*',
      },
      // 如果存在 `x-authorized` 请求头且包含匹配值
      // 将应用此重定向
      {
        source: '/',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        permanent: false,
        destination: '/home?authorized=:authorized',
      },
      // 如果主机是 `example.com`
      // 将应用此重定向
      {
        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', // 自动变为 /docs/with-basePath
        destination: '/another', // 自动变为 /docs/another
        permanent: false,
      },
      {
        // 由于设置了 basePath: false 不会添加 /docs
        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', // 自动处理所有语言环境
        destination: '/another', // 自动传递语言环境
        permanent: false,
      },
      {
        // 由于设置了 locale: false 不会自动处理语言环境
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
        permanent: false,
      },
      {
        // 这将匹配 '/' 因为 `en` 是默认语言环境
        source: '/en',
        destination: '/en/another',
        locale: false,
        permanent: false,
      },
      // 即使设置了 locale: false 也可以匹配所有语言环境
      {
        source: '/:locale/page',
        destination: '/en/newpage',
        permanent: false,
        locale: false,
      },
      {
        // 这将转换为 /(en|fr|de)/(.*) 因此不会匹配顶级
        // `/` 或 `/fr` 路由，像 /:path* 那样
        source: '/(.*)',
        destination: '/another',
        permanent: false,
      },
    ]
  },
}

在极少数情况下，您可能需要为旧版 HTTP 客户端分配自定义状态码以实现正确重定向。此时可以使用 statusCode 属性替代 permanent 属性，但不能同时使用两者。为确保 IE11 兼容性，308 状态码会自动添加 Refresh 请求头。

其他重定向方式

版本历史

版本变更
v13.3.0新增 missing 功能
v10.2.0新增 has 功能
v9.5.0新增 redirects 功能

reactStrictMode

Next.js 运行时现已全面兼容严格模式 (Strict Mode)，了解如何启用该功能

rewrites

为你的 Next.js 应用添加重定向规则 (rewrites)。