NNext.js 中文网 GitHub

rewrites

为你的 Next.js 应用添加重写规则。

重写使你可以将传入的请求路径映射到不同的目标路径。

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

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

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

next.config.js
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 起,可以更改此行为并进行更精细的控制:

next.config.js
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 检查路由的顺序是:

  1. 检查/应用 headers
  2. 检查/应用 redirects
  3. proxy
  4. beforeFiles 重写:对于每个条目,如果 source、has 和 missing 与请求匹配,则将其重写为 destination。
  5. 检查/提供来自 public 目录的静态文件、_next/static 文件和非动态页面
  6. 按顺序尝试 afterFiles 重写。如果 source、has 和 missing 与请求匹配,则将其重写为 destination;解析为静态文件、页面或动态路由的第一个重写将被提供。
  7. 动态路由(例如 app/blog/[slug]/page.tsx)与当前路径匹配
  8. 检查/应用 fallback 重写,这些重写在渲染 404 页面之前、动态路由/所有静态资源检查之后应用。如果你在 getStaticPaths 中使用 fallback: true/'blocking',这些动态路由优先于 next.config.js 中定义的 fallback rewrites。
  1. 检查/应用 headers
  2. 检查/应用 redirects
  3. beforeFiles 重写:对于每个条目,如果 source 与请求匹配,则将其重写为 destination。
  4. 检查/提供来自 public 目录的静态文件、_next/static 文件和非动态页面
  5. 按顺序尝试 afterFiles 重写。如果 source 与请求匹配,则将其重写为 destination;解析为静态文件、页面或动态路由的第一个重写将被提供。
  6. 动态路由(例如 pages/blog/[slug].tsx)与当前路径匹配
  7. 检查/应用 fallback 重写,这些重写在渲染 404 页面之前、动态路由/所有静态资源检查之后应用。如果你在 getStaticPaths 中使用 fallback: true/'blocking',next.config.js 中定义的 fallback rewrites 将不会运行。

重写参数#

在重写中使用参数时,如果 destination 中未使用任何参数,则这些参数默认会作为查询参数传递。

next.config.js
module.exports = {
  rewrites() {
    return [
      {
        source: '/old-about/:path*',
        destination: '/about', // 此处未使用 :path 参数,因此它将自动作为查询参数传递
      },
    ]
  },
}

如果某个参数在目标路径中被使用,则任何参数都不会自动作为查询参数传递。

next.config.js
module.exports = {
  rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: '/:path*', // 此处使用了 :path 参数,因此不会自动作为查询参数传递
      },
    ]
  },
}

如果目标路径中已经使用了某个参数,你仍可以通过在 destination 中指定查询来手动在查询中传递参数。

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

小知识:来自自动静态优化的静态页面或来自重写的预渲染参数将在水合后在客户端解析,并在查询中提供。

路径匹配#

允许路径匹配,例如 /blog/:slug 将匹配 /blog/first-post(不匹配嵌套路径):

next.config.js
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:

next.config.js
module.exports = {
  rewrites() {
    return [
      {
        source: '/blog/:slug*',
        destination: '/news/:slug*', // 匹配的参数可用于目标路径
      },
    ]
  },
}

正则表达式路径匹配#

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

next.config.js
module.exports = {
  rewrites() {
    return [
      {
        source: '/old-blog/:post(\\d{1,})',
        destination: '/blog/:post', // 匹配的参数可用于目标路径
      },
    ]
  },
}

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

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

要仅在标头、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。
next.config.js
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 路由重定向到外部站点的重写示例。

next.config.js
module.exports = {
  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,
  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 = {
  rewrites() {
    return {
      fallback: [
        {
          source: '/:path*',
          destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*`,
        },
      ],
    }
  },
}

支持 basePath 的重写#

在将 basePath 支持与重写结合使用时,每个 source 和 destination 都会自动加上 basePath 前缀,除非你在重写中添加 basePath: false:

next.config.js
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 添加区域设置前缀,才能正确匹配。

next.config.js
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新增标头。
Next.js 中文网