rewrites

重写允许你将传入请求路径映射到不同的目标路径。

重写充当 URL 代理并隐藏目标路径，使其看起来用户没有改变他们在网站上的位置。相比之下，重定向将重定向到新页面并显示 URL 变化。

要使用重写，你可以在 next.config.js 中使用 rewrites 键：

next.config.js

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

重写应用于客户端路由，例如 <Link href="/about"> 在上面的例子中会有重写应用。

rewrites 是一个异步函数，期望返回一个数组或对象的数组（见下文），其中包含具有 source 和 destination 属性的对象：

source: String - 是传入请求路径模式。
destination: String - 是你希望路由到的路径。
basePath: false 或 undefined - 如果为 false，basePath 在匹配时不会被包含，仅用于外部重写。
locale: false 或 undefined - 是否在匹配时不包含区域设置。
has 是一个包含 has 对象的数组，具有 type、key 和 value 属性。
missing 是一个包含 missing 对象的数组，具有 type、key 和 value 属性。

当 rewrites 函数返回一个数组时，重写会在检查文件系统（页面和 /public 文件）之后和动态路由之前应用。当 rewrites 函数返回一个具有特定形状的对象数组时，这种行为可以改变并更精细地控制，从 Next.js v10.1 开始：

next.config.js

module.exports = {
  async rewrites() {
    return {
      beforeFiles: [
        // 这些重写在检查 headers/redirects 之后
        // 和所有文件包括 _next/public 文件之前
        // 允许覆盖页面文件
        {
          source: "/some-page",
          destination: "/somewhere-else",
          has: [{ type: "query", key: "overrideMe" }],
        },
      ],
      afterFiles: [
        // 这些重写在检查页面/公共文件之后
        // 但在动态路由之前
        {
          source: "/non-existent",
          destination: "/somewhere-else",
        },
      ],
      fallback: [
        // 这些重写在检查页面/公共文件
        // 和动态路由之后
        {
          source: "/:path*",
          destination: `https://my-old-site.com/:path*`,
        },
      ],
    };
  },
};

值得注意的是：beforeFiles 中的重写在匹配源之后不会立即检查文件系统/动态路由，它们会继续检查所有 beforeFiles。

Next.js 路由的检查顺序是：

headers 被检查/应用
redirects 被检查/应用
beforeFiles 重写被检查/应用
来自 public 目录、_next/static 文件和非动态页面的静态文件被检查/服务
afterFiles 重写被检查/应用，如果这些重写之一匹配，我们会在每次匹配后检查动态路由/静态文件
fallback 重写被检查/应用，这些在渲染 404 页面之前和动态路由/所有静态资源被检查之后应用。如果你在 getStaticPaths 中使用 fallback: true/'blocking'，在 next.config.js 中定义的 fallback 重写将不会运行。

重写参数

当在重写中使用参数时，默认情况下参数会在查询中传递，当参数未在 destination 中使用时。

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: "/old-about/:path*",
        destination: "/about", // :path 参数在这里未使用，因此会自动传递到查询中
      },
    ];
  },
};

如果参数在目标中使用，则不会自动传递任何参数。

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: "/docs/:path*",
        destination: "/:path*", // :path 参数在这里使用，因此不会自动传递到查询中
      },
    ];
  },
};

你仍然可以在目标中手动传递参数，如果其中一个参数已经在目标中使用，可以通过在 destination 中指定查询来实现。

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: "/:first/:second",
        destination: "/:first?second=:second",
        // 由于 :first 参数在目标中使用，:second 参数
        // 不会自动添加到查询中，尽管我们可以手动添加
        // 如上所示
      },
    ];
  },
};

值得注意的是：来自自动静态优化或预渲染的静态页面参数在客户端水合后会被解析并在查询中提供。

路径匹配

路径匹配是允许的，例如 /blog/:slug 将匹配 /blog/hello-world（不匹配嵌套路径）：

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: "/blog/:slug",
        destination: "/news/:slug", // 匹配的参数可以在目标中使用
      },
    ];
  },
};

通配符路径匹配

要匹配通配符路径，你可以在参数后使用 *，例如 /blog/:slug* 将匹配 /blog/a/b/c/d/hello-world：

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: "/blog/:slug*",
        destination: "/news/:slug*", // 匹配的参数可以在目标中使用
      },
    ];
  },
};

正则表达式路径匹配

要匹配正则表达式路径，你可以在参数后用括号包裹正则表达式，例如 /blog/:slug(\\d{1,}) 将匹配 /blog/123 但不匹配 /blog/abc：

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: "/old-blog/:post(\\d{1,})",
        destination: "/blog/:post", // 匹配的参数可以在目标中使用
      },
    ];
  },
};

以下字符 (, ), {, }, [, ], |, \, ^, ., :, *, +, -, ?, $ 用于正则表达式路径匹配，因此在 source 中作为非特殊值使用时，必须在其前添加 \\ 进行转义：

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        // 这将匹配 `/english(default)/something` 的请求
        source: "/english\\(default\\)/:slug",
        destination: "/en-us/:slug",
      },
    ];
  },
};

头部、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 rewrites() {
    return [
      // 如果头部 `x-rewrite-me` 存在，
      // 此重写将应用
      {
        source: "/:path*",
        has: [
          {
            type: "header",
            key: "x-rewrite-me",
          },
        ],
        destination: "/another-page",
      },
      // 如果头部 `x-rewrite-me` 不存在，
      // 此重写将应用
      {
        source: "/:path*",
        missing: [
          {
            type: "header",
            key: "x-rewrite-me",
          },
        ],
        destination: "/another-page",
      },
      // 如果源、查询和 Cookie 匹配，
      // 此重写将应用
      {
        source: "/specific/:path*",
        has: [
          {
            type: "query",
            key: "page",
            // page 值在目标中不可用，因为提供了值且未使用命名捕获组，例如 (?<page>home)
            value: "home",
          },
          {
            type: "cookie",
            key: "authorized",
            value: "true",
          },
        ],
        destination: "/:path*/home",
      },
      // 如果头部 `x-authorized` 存在且
      // 包含匹配值，此重写将应用
      {
        source: "/:path*",
        has: [
          {
            type: "header",
            key: "x-authorized",
            value: "(?<authorized>yes|true)",
          },
        ],
        destination: "/home?authorized=:authorized",
      },
      // 如果主机是 `example.com`，
      // 此重写将应用
      {
        source: "/:path*",
        has: [
          {
            type: "host",
            value: "example.com",
          },
        ],
        destination: "/another-page",
      },
    ];
  },
};

重写到外部 URL

示例

重写允许你重写到外部 URL。这对于逐步采用 Next.js 特别有用。以下是一个重写示例，将主应用的 /blog 路由重定向到外部站点。

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: "/blog",
        destination: "https://example.com/blog",
      },
      {
        source: "/blog/:slug",
        destination: "https://example.com/blog/:slug", // 匹配的参数可以在目标中使用
      },
    ];
  },
};

如果你使用 trailingSlash: true，你还需要在 source 参数中插入尾部斜杠。如果目标服务器也期望尾部斜杠，它应该包含在 destination 参数中。

next.config.js

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 时更改重写配置

next.config.js

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

带有 basePath 支持的重写

当利用 basePath 支持进行重写时，除非在重写中添加 basePath: false，否则每个 source 和 destination 会自动加上 basePath 前缀：

next.config.js

module.exports = {
  basePath: "/docs",
 
  async rewrites() {
    return [
      {
        source: "/with-basePath", // 自动变为 /docs/with-basePath
        destination: "/another", // 自动变为 /docs/another
      },
      {
        // 不添加 /docs 到 /without-basePath，因为设置了 basePath: false
        // 注意：这不能用于内部重写，例如 `destination: '/another'`
        source: "/without-basePath",
        destination: "https://example.com",
        basePath: 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 rewrites() {
    return [
      {
        source: "/with-locale", // 自动处理所有区域设置
        destination: "/another", // 自动传递区域设置
      },
      {
        // 不自动处理区域设置，因为设置了 locale: false
        source: "/nl/with-locale-manual",
        destination: "/nl/another",
        locale: false,
      },
      {
        // 这匹配 '/'，因为 `en` 是 defaultLocale
        source: "/en",
        destination: "/en/another",
        locale: false,
      },
      {
        // 即使设置了 locale: false，也可以匹配所有区域设置
        source: "/:locale/api-alias/:path*",
        destination: "/api/:path*",
        locale: false,
      },
      {
        // 这被转换为 /(en|fr|de)/(.*)，因此不会像 /:path* 那样匹配顶级
        // `/` 或 `/fr` 路由
        source: "/(.*)",
        destination: "/another",
      },
    ];
  },
};

版本历史

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