rewrites

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

Rewrites 充当 URL 代理并屏蔽目标路径，使用户看起来没有更改在站点上的位置。相比之下，redirects 将重定向到新页面并显示 URL 更改。

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

next.config.js

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

Rewrites 应用于客户端路由，在上面的示例中，<Link href="/about"> 将应用 rewrite。

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

source: String - 是传入的请求路径模式。
destination: String 是你要路由到的路径。
basePath: false 或 undefined - 如果为 false，则匹配时不会包含 basePath，仅可用于外部 rewrites。
locale: false 或 undefined - 是否在匹配时不应包含 locale。
has 是 has 对象的数组，具有 type、key 和 value 属性。
missing 是 missing 对象的数组，具有 type、key 和 value 属性。

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

next.config.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 中的 rewrites 在匹配源之后不会立即检查文件系统/动态路由，它们会继续检查直到所有 beforeFiles 都已检查完毕。

Next.js 路由的检查顺序是

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

Rewrite 参数

当在 rewrite 中使用参数时，如果 destination 中未使用任何参数，则默认情况下参数将传递到查询中。

next.config.js

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
      },
    ]
  },
}

如果在 destination 中使用了参数，则不会自动在查询中传递任何参数。

next.config.js

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 中已使用某个参数，你仍然可以通过在 destination 中指定查询来手动在查询中传递参数。

next.config.js

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
      },
    ]
  },
}

须知：来自自动静态优化或预渲染的静态页面，其来自 rewrites 的参数将在客户端 hydration 后解析并在查询中提供。

路径匹配

允许路径匹配，例如 /blog/:slug 将匹配 /blog/hello-world（没有嵌套路径）

next.config.js

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

next.config.js

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

next.config.js

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

以下字符 (, ), {, }, [, ], |, \, ^, ., :, *, +, -, ?, $ 用于正则表达式路径匹配，因此当在 source 中用作非特殊值时，必须通过在它们之前添加 \\ 来转义它们

next.config.js

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

为了仅在 header、cookie 或 query 值也匹配 has 字段或不匹配 missing 字段时才匹配 rewrite，可以使用 has 字段或 missing 字段。source 和所有 has 项都必须匹配，并且所有 missing 项都必须不匹配，rewrite 才能应用。

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

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

next.config.js

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

示例

Rewrites 允许你重写到外部 URL。这对于增量采用 Next.js 尤其有用。以下是将主应用的 /blog 路由重定向到外部站点的示例 rewrite。

next.config.js

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 参数中。

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 时，不必更改 rewrites 配置

next.config.js

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

支持 basePath 的 rewrites

当利用 basePath 支持进行 rewrites 时，每个 source 和 destination 都会自动添加 basePath 前缀，除非你向 rewrite 添加 basePath: false

next.config.js

module.exports = {
  basePath: '/docs',
 
  async rewrites() {
    return [
      {
        source: '/with-basePath', // automatically becomes /docs/with-basePath
        destination: '/another', // automatically becomes /docs/another
      },
      {
        // does not add /docs to /without-basePath since basePath: false is set
        // Note: this can not be used for internal rewrites e.g. `destination: '/another'`
        source: '/without-basePath',
        destination: 'https://example.com',
        basePath: false,
      },
    ]
  },
}

支持 i18n 的 rewrites

当利用 i18n 支持进行 rewrites 时，每个 source 和 destination 都会自动添加前缀以处理配置的 locales，除非你向 rewrite 添加 locale: false。如果使用 locale: false，你必须在 source 和 destination 中添加 locale 前缀才能正确匹配。

next.config.js

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },
 
  async rewrites() {
    return [
      {
        source: '/with-locale', // automatically handles all locales
        destination: '/another', // automatically passes the locale on
      },
      {
        // does not handle locales automatically since locale: false is set
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
      },
      {
        // this matches '/' since `en` is the defaultLocale
        source: '/en',
        destination: '/en/another',
        locale: false,
      },
      {
        // it's possible to match all locales even when locale: false is set
        source: '/:locale/api-alias/:path*',
        destination: '/api/:path*',
        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',
      },
    ]
  },
}

版本历史

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