rewrites
为你的 Next.js 应用添加重写规则。
重写使你可以将传入的请求路径映射到不同的目标路径。
重写充当 URL 代理并隐藏目标路径,让用户看起来没有改变其在站点上的位置。相比之下,重定向会重新路由到新页面并显示 URL 变化。
重写充当 URL 代理并隐藏目标路径,让用户看起来没有改变其在站点上的位置。相比之下,重定向会重新路由到新页面并显示 URL 变化。
要使用重写,你可以在 next.config.js 中使用 rewrites 键:
module.exports = {
rewrites() {
return [
{
source: '/about',
destination: '/',
},
]
},
}重写会应用于客户端路由。在上面的示例中,导航到 <Link href="/about"> 将提供来自 / 的内容,同时保持 URL 为 /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 起,可以更改此行为并进行更精细的控制:
module.exports = {
rewrites() {
return {
beforeFiles: [
// 这些重写在标头/重定向之后检查
// 在所有文件(包括 _next/static 和 public 文件)之前检查,从而
// 可以覆盖页面文件
{
source: '/some-page',
destination: '/somewhere-else',
has: [{ type: 'query', key: 'overrideMe' }],
},
],
afterFiles: [
// 这些重写在 pages/public 文件检查之后
// 但在动态路由之前检查
{
source: '/non-existent',
destination: '/somewhere-else',
},
],
fallback: [
// 这些重写在 pages/public 文件和
// 动态路由都检查之后才检查
{
source: '/:path*',
destination: `https://my-old-site.com/:path*`,
},
],
}
},
}小知识:
beforeFiles中的重写在匹配到 source 后不会立即检查文件系统/动态路由,它们会继续检查,直到所有beforeFiles都被检查完。
Next.js 检查路由的顺序是:
- 检查/应用 headers
- 检查/应用 redirects
- proxy
beforeFiles重写:对于每个条目,如果source、has和missing与请求匹配,则将其重写为destination。- 检查/提供来自 public 目录的静态文件、
_next/static文件和非动态页面 - 按顺序尝试
afterFiles重写。如果source、has和missing与请求匹配,则将其重写为destination;解析为静态文件、页面或动态路由的第一个重写将被提供。 - 动态路由(例如
app/blog/[slug]/page.tsx)与当前路径匹配 - 检查/应用
fallback重写,这些重写在渲染 404 页面之前、动态路由/所有静态资源检查之后应用。如果你在getStaticPaths中使用 fallback: true/'blocking',这些动态路由优先于next.config.js中定义的 fallbackrewrites。
- 检查/应用 headers
- 检查/应用 redirects
beforeFiles重写:对于每个条目,如果source与请求匹配,则将其重写为destination。- 检查/提供来自 public 目录的静态文件、
_next/static文件和非动态页面 - 按顺序尝试
afterFiles重写。如果source与请求匹配,则将其重写为destination;解析为静态文件、页面或动态路由的第一个重写将被提供。 - 动态路由(例如
pages/blog/[slug].tsx)与当前路径匹配 - 检查/应用
fallback重写,这些重写在渲染 404 页面之前、动态路由/所有静态资源检查之后应用。如果你在getStaticPaths中使用 fallback: true/'blocking',next.config.js中定义的 fallbackrewrites将不会运行。
重写参数#
在重写中使用参数时,如果 destination 中未使用任何参数,则这些参数默认会作为查询参数传递。
module.exports = {
rewrites() {
return [
{
source: '/old-about/:path*',
destination: '/about', // 此处未使用 :path 参数,因此它将自动作为查询参数传递
},
]
},
}如果某个参数在目标路径中被使用,则任何参数都不会自动作为查询参数传递。
module.exports = {
rewrites() {
return [
{
source: '/docs/:path*',
destination: '/:path*', // 此处使用了 :path 参数,因此不会自动作为查询参数传递
},
]
},
}如果目标路径中已经使用了某个参数,你仍可以通过在 destination 中指定查询来手动在查询中传递参数。
module.exports = {
rewrites() {
return [
{
source: '/:first/:second',
destination: '/:first?second=:second',
// 由于 :first 参数在目标路径中被使用,:second 参数
// 不会自动添加到查询中,尽管我们可以手动添加它
// 如上所示
},
]
},
}路径匹配#
允许路径匹配,例如 /blog/:slug 将匹配 /blog/first-post(不匹配嵌套路径):
module.exports = {
rewrites() {
return [
{
source: '/blog/:slug',
destination: '/news/:slug', // 匹配的参数可用于目标路径
},
]
},
}模式 /blog/:slug 匹配 /blog/first-post 和 /blog/post-1,但不匹配 /blog/a/b(不匹配嵌套路径)。模式锚定在开头:/blog/:slug 不会匹配 /archive/blog/first-post。
你可以对参数使用修饰符:*(零个或多个)、+(一个或多个)、?(零个或一个)。例如,/blog/:slug* 匹配 /blog、/blog/a 和 /blog/a/b/c。
有关更多细节,请阅读 path-to-regexp 文档。
通配符路径匹配#
要匹配通配符路径,可以在参数后使用 *,例如 /blog/:slug* 将匹配 /blog/a/b/c/d/hello-world:
module.exports = {
rewrites() {
return [
{
source: '/blog/:slug*',
destination: '/news/:slug*', // 匹配的参数可用于目标路径
},
]
},
}正则表达式路径匹配#
要匹配正则表达式路径,可以将正则表达式包裹在参数后的括号中,例如 /blog/:slug(\\d{1,}) 将匹配 /blog/123 但不匹配 /blog/abc:
module.exports = {
rewrites() {
return [
{
source: '/old-blog/:post(\\d{1,})',
destination: '/blog/:post', // 匹配的参数可用于目标路径
},
]
},
}以下字符 (, ), {, }, [, ], |, \, ^, ., :, *, +, -, ?, $ 用于正则表达式路径匹配,因此当它们在 source 中作为非特殊值使用时,必须通过在它们前面添加 \\ 来进行转义:
module.exports = {
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—— 要检查的值,若为 undefined 则任何值都会匹配。可以使用类似正则表达式的字符串来捕获值的特定部分,例如,如果将值first-(?<paramName>.*)用于first-second,则可在目标路径中通过:paramName使用second。
module.exports = {
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',
},
// 如果 source、查询和 cookie 都匹配,
// 将应用此重写
{
source: '/specific/:path*',
has: [
{
type: 'query',
key: 'page',
// 由于提供了值且未使用命名捕获组(例如 (?<page>home)),
// page 值将无法在目标路径中使用
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#
<details> <summary>示例</summary>
</details>
重写使你可以重写到外部 URL。这对于逐步采用 Next.js 特别有用。以下是一个将主应用的 /blog 路由重定向到外部站点的重写示例。
module.exports = {
rewrites() {
return [
{
source: '/blog',
destination: 'https://example.com/blog',
},
{
source: '/blog/:slug',
destination: 'https://example.com/blog/:slug', // 匹配的参数可用于目标路径
},
]
},
}如果你使用 trailingSlash: true,还需要在 source 参数中插入尾部斜杠。如果目标服务器也需要尾部斜杠,则应在 destination 参数中也包含它。
module.exports = {
trailingSlash: true,
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 时,你无需更改重写配置。
module.exports = {
rewrites() {
return {
fallback: [
{
source: '/:path*',
destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*`,
},
],
}
},
}支持 basePath 的重写#
在将 basePath 支持与重写结合使用时,每个 source 和 destination 都会自动加上 basePath 前缀,除非你在重写中添加 basePath: false:
module.exports = {
basePath: '/docs',
rewrites() {
return [
{
source: '/with-basePath', // 自动变为 /docs/with-basePath
destination: '/another', // 自动变为 /docs/another
},
{
// 由于设置了 basePath: false,不会为 /without-basePath 添加 /docs
// 注意:这不能用于内部重写,例如 `destination: '/another'`
source: '/without-basePath',
destination: 'https://example.com',
basePath: false,
},
]
},
}支持 i18n 的重写#
在将 i18n 支持与重写结合使用时,每个 source 和 destination 都会自动添加前缀以处理配置的 locales,除非你在重写中添加 locale: false。如果使用了 locale: false,你必须为 source 和 destination 添加区域设置前缀,才能正确匹配。
module.exports = {
i18n: {
locales: ['en', 'fr', 'de'],
defaultLocale: 'en',
},
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 | 新增标头。 |