重定向（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", // 匹配的参数可以在目标中使用
        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 - 要检查的值，如果未定义，任何值都将匹配。可以使用类似正则表达式的字符串来捕获值的特定部分，例如，如果值 first-(?<paramName>.*) 用于 first-second，则可以在目标中使用 :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 值在目标中不可用，因为提供了值且未使用命名捕获组，例如 (?<page>home)
            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 支持进行重定向时，除非在重定向中添加 basePath: false，否则每个 source 和 destination 会自动加上 basePath 前缀：

next.config.js

module.exports = {
  basePath: "/docs",
 
  async redirects() {
    return [
      {
        source: "/with-basePath", // 自动变为 /docs/with-basePath
        destination: "/another", // 自动变为 /docs/another
        permanent: false,
      },
      {
        // 不添加 /docs，因为设置了 basePath: false
        source: "/without-basePath",
        destination: "https://example.com",
        basePath: false,
        permanent: false,
      },
    ];
  },
};

带有 i18n 支持的重定向

当利用 i18n 支持进行重定向时，除非在重定向中添加 locale: false，否则每个 source 和 destination 会自动加上配置的 locales 前缀。如果使用 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` 是 defaultLocale
        source: "/en",
        destination: "/en/another",
        locale: false,
        permanent: false,
      },
      // 即使设置了 locale: false，也可以匹配所有区域设置
      {
        source: "/:locale/page",
        destination: "/en/newpage",
        permanent: false,
        locale: false,
      },
      {
        // 这被转换为 /(en|fr|de)/(.*)，因此不会像 /:path* 那样匹配顶级
        // `/` 或 `/fr` 路由
        source: "/(.*)",
        destination: "/another",
        permanent: false,
      },
    ];
  },
};

在某些罕见情况下，你可能需要为旧版 HTTP 客户端分配自定义状态码以正确重定向。在这些情况下，你可以使用 statusCode 属性而不是 permanent 属性，但不能同时使用两者。为了确保 IE11 兼容性，308 状态码会自动添加 Refresh 头部。

其他重定向

在 API 路由和路由处理程序中，你可以根据传入请求进行重定向。
在 getStaticProps 和 getServerSideProps 中，你可以重定向特定页面在请求时。

版本历史

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