rewrites
重写 (rewrites) 允许您将传入的请求路径映射到不同的目标路径。
重写充当 URL 代理并隐藏目标路径,使用户看起来像是没有改变他们在网站上的位置。相比之下,重定向 (redirects) 会重新路由到新页面并显示 URL 变化。
要使用重写功能,您可以在 next.config.js
中使用 rewrites
键:
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
是包含type
、key
和value
属性的 has 对象 数组missing
是包含type
、key
和value
属性的 missing 对象 数组
当 rewrites
函数返回数组时,重写会在检查文件系统(页面和 /public
文件)之后、动态路由之前应用。从 Next.js v10.1
开始,当 rewrites
函数返回特定结构的数组对象时,可以更改并更精细地控制此行为:
module.exports = {
async rewrites() {
return {
beforeFiles: [
// 这些重写在检查 headers/redirects 之后
// 但在所有文件(包括 _next/public 文件)之前检查
// 允许覆盖页面文件
{
source: '/some-page',
destination: '/somewhere-else',
has: [{ type: 'query', key: 'overrideMe' }],
},
],
afterFiles: [
// 这些重写在检查 pages/public 文件之后
// 但在动态路由之前检查
{
source: '/non-existent',
destination: '/somewhere-else',
},
],
fallback: [
// 这些重写在检查 pages/public 文件和动态路由之后
// 在渲染 404 页面之前应用
{
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
中没有使用任何参数,默认情况下参数会传递到查询中。
module.exports = {
async rewrites() {
return [
{
source: '/old-about/:path*',
destination: '/about', // 此处未使用 :path 参数,因此会自动传递到查询中
},
]
},
}
如果在目标路径中使用了参数,则不会自动将任何参数传递到查询中。
module.exports = {
async rewrites() {
return [
{
source: '/docs/:path*',
destination: '/:path*', // 此处使用了 :path 参数,因此不会自动传递到查询中
},
]
},
}
如果目标路径中已经使用了参数,您仍然可以通过在 destination
中指定查询来手动传递参数。
module.exports = {
async rewrites() {
return [
{
source: '/:first/:second',
destination: '/:first?second=:second',
// 由于目标路径中使用了 :first 参数,:second 参数不会自动添加到查询中
// 但我们可以像上面那样手动添加
},
]
},
}
须知:来自 自动静态优化 (Automatic Static Optimization) 或 预渲染 (prerendering) 的静态页面的重写参数将在客户端水合后解析并出现在查询中。
路径匹配
允许路径匹配,例如 /blog/:slug
将匹配 /blog/hello-world
(无嵌套路径):
module.exports = {
async rewrites() {
return [
{
source: '/blog/:slug',
destination: '/news/:slug', // 匹配的参数可用于目标路径
},
]
},
}
通配符路径匹配
要匹配通配符路径,您可以在参数后使用 *
,例如 /blog/:slug*
将匹配 /blog/a/b/c/d/hello-world
:
module.exports = {
async rewrites() {
return [
{
source: '/blog/:slug*',
destination: '/news/:slug*', // 匹配的参数可用于目标路径
},
]
},
}
正则表达式路径匹配
要匹配正则表达式路径,您可以将正则表达式包裹在参数后的括号中,例如 /blog/:slug(\\d{1,})
将匹配 /blog/123
但不匹配 /blog/abc
:
module.exports = {
async rewrites() {
return [
{
source: '/old-blog/:post(\\d{1,})',
destination: '/blog/:post', // 匹配的参数可用于目标路径
},
]
},
}
以下字符 (
, )
, {
, }
, [
, ]
, |
, \
, ^
, .
, :
, *
, +
, -
, ?
, $
用于正则表达式路径匹配,因此当在 source
中作为非特殊值使用时,必须通过在它们前面添加 \\
来转义:
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
,则second
可以在目标路径中使用:paramName
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>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
重写允许您重写到外部 URL。这对于逐步采用 Next.js 特别有用。以下是重写主应用的 /blog
路由到外部站点的示例。
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
参数中。
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 时,您无需更改重写配置。
module.exports = {
async 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',
async rewrites() {
return [
{
source: '/with-basePath', // 自动变为 /docs/with-basePath
destination: '/another', // 自动变为 /docs/another
},
{
// 由于设置了 basePath: false,不会将 /docs 添加到 /without-basePath
// 注意:不能用于内部重写,例如 `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',
},
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 功能。 |