Rewrites

重写允许您将传入的请求路径映射到不同的目标路径。

重写仅在 Node.js 环境中可用，不会影响客户端路由。

要使用重写，您可以使用 blitz.config.js 中的 rewrites 键：

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

rewrites 是一个异步函数，期望返回一个包含具有 source 和 destination 属性的对象的数组：

source：String——是传入请求的路径模式
destination：String 是你想要路由到的目标路径
locale: false 或 undefined——匹配时是否不应该包含语言环境。
has：具有 type、key 和 value 属性的 has 对象数组。

默认情况下，在检查文件系统（页面和 /public 文件）之后和动态路由之前使用重写。

module.exports = {
  async rewrites() {
    return {
      beforeFiles: [
        // 在 headers/redirects 之后，允许覆盖页面文件的页面/公共文件之前检查这些重写
        {
          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*`,
        },
      ],
    }
  },
}

重写参数

在重写中使用参数时，如果在 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 中已经使用了参数，你仍然可以通过在 destination 中指定查询来手动在查询中传递参数。

module.exports = {
  async rewrites() {
    return [
      {
        source: "/:first/:second",
        destination: "/:first?second=:second",
        // 由于 :first 参数用于目标中，因此 :second 参数不会自动添加到查询中，尽管我们可以手动添加它，如上所示
      },
    ]
  },
}

路径匹配

允许路径匹配，例如 /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 redirects() {
    return [
      {
        // 这将匹配欲请求的 `/english(default)/something`
        source: "/english\\(default\\)/:slug",
        destination: "/en-us/:slug",
        permanent: false,
      },
    ]
  },
}

要仅在 header、cookie 或查询值也匹配 has 字段时才匹配重写并使用。source 和所有 has 项都必须匹配才能使用重写。

has 具有以下字段：

type：String——必须是 header、cookie、host 或 query。
key：String——所选类型中要匹配的键。
value：String 或 undefined——要检查的值，如果 undefined 将匹配任意值。像字符串这样的正则表达式可用于捕获值的特定部分，例如如果值first-(?<paramName>.*) 用于 first-second，那么 second 将在目的地中使用 :paramName。

module.exports = {
  async rewrites() {
    return [
      // 如果 header 中有 `x-redirect-me` 存在，
      // 将使用此重写
      {
        source: "/:path*",
        has: [
          {
            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",
      },
      // 如果 header `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。尤其对于一个逐步采用 Blitz.js 的场景来说很重要。

module.exports = {
  async rewrites() {
    return [
      {
        source: "/blog/:slug",
        destination: "https://example.com/blog/:slug", // Matched parameters can be used in the destination
      },
    ]
  },
}

逐步采用 Blitz.js

在检查所有 Blitz.js 路由后，你还可以让 Blitz.js 回退来代理到现有网站。

这样你就不必在更多页面迁移到 Blitz.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 前面加上一个 locale 设置，才能正确匹配。

module.exports = {
  i18n: {
    locales: ["en", "fr", "de"],
    defaultLocale: "en",
  },

  async rewrites() {
    return [
      {
        source: "/with-locale", // 自动处理所有 locales
        destination: "/another", // 自动传递 locales
      },
      {
        // 自从 locale: false 被设置后，将不自动处理 locales
        source: "/nl/with-locale-manual",
        destination: "/nl/another",
        locale: false,
      },
      {
        // 自动 `en` 是 defaultLocale，将匹配 `/`
        source: "/en",
        destination: "/en/another",
        locale: false,
      },
      {
        // 这被转换为 /(en|fr|de)/(.*) 所以不会像 /:path*
        // 这样地匹配顶级 `/` 或 `/fr` 路由
        source: "/(.*)",
        destination: "/another",
      },
    ]
  },
}

Topics