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 是具有 type、key 和 value 属性的 has 对象数组。
missing 是具有 type、key 和 value 属性的 missing 对象数组。

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

next.config.js
module.exports = {
  async rewrites() {
    return {
      beforeFiles: [
        // 这些重写在头部/重定向之后检查
        // 在所有文件（包括 _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 路由检查的顺序是：

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

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

重写参数

在重写中使用参数时，当 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，则 second 可以在目标中使用 :paramName。

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>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 支持时，每个 source 和 destination 都会自动添加 basePath 前缀，除非你在重写中添加 basePath: false：

next.config.js
module.exports = {
  basePath: '/docs',

  async 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',
  },

  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)/(.*)，所以不会匹配顶级
        // `/` 或 `/fr` 路由，就像 /:path* 那样
        source: '/(.*)',
        destination: '/another',
      },
    ]
  },
}

版本历史

版本	更改
`v13.3.0`	添加 `missing`。
`v10.2.0`	添加 `has`。
`v9.5.0`	添加头部。

重写参数​

路径匹配​

通配符路径匹配​

正则表达式路径匹配​

头部、Cookie 和查询匹配​

重写到外部 URL​

逐步采用 Next.js​

支持 basePath 的重写​

支持 i18n 的重写​

版本历史​