重新導向 (redirects)

重新導向功能允許您將傳入的請求路徑重新導向到不同的目標路徑。

要使用重新導向功能，您可以在 next.config.js 中使用 redirects 鍵：

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/about',
        destination: '/',
        permanent: true,
      },
    ]
  },
}

redirects 是一個非同步函式，預期回傳一個包含物件的陣列，這些物件具有 source、destination 和 permanent 屬性：

source 是傳入的請求路徑模式。
destination 是您想要路由到的路徑。
permanent true 或 false - 如果為 true，將使用 308 狀態碼，指示客戶端/搜尋引擎永久快取此重新導向；如果為 false，則使用 307 狀態碼，表示臨時重新導向且不會快取。

為什麼 Next.js 使用 307 和 308？ 傳統上，302 用於臨時重新導向，301 用於永久重新導向，但許多瀏覽器會將重新導向的請求方法更改為 GET，無論原始方法為何。例如，如果瀏覽器發送一個 POST /v1/users 請求，該請求返回狀態碼 302 並帶有位置 /v2/users，則後續請求可能是 GET /v2/users 而非預期的 POST /v2/users。Next.js 使用 307 臨時重新導向和 308 永久重新導向狀態碼，以明確保留使用的請求方法。

basePath: false 或 undefined - 如果為 false，則在匹配時不會包含 basePath，僅可用於外部重新導向。
locale: false 或 undefined - 是否在匹配時不包含語言環境。
has 是一個包含 type、key 和 value 屬性的 has 物件陣列。
missing 是一個包含 type、key 和 value 屬性的 missing 物件陣列。

重新導向會在檔案系統（包括頁面和 /public 檔案）之前進行檢查。

當使用頁面路由器時，除非存在中介軟體並匹配路徑，否則重新導向不會應用於客戶端路由（Link、router.push）。

當應用重新導向時，請求中提供的任何查詢值都會傳遞到重新導向目標。例如，請看以下重新導向配置：

{
  source: '/old-blog/:path*',
  destination: '/blog/:path*',
  permanent: false
}

當請求 /old-blog/post-1?hello=world 時，客戶端將被重新導向到 /blog/post-1?hello=world。

路徑匹配

允許路徑匹配，例如 /old-blog/:slug 將匹配 /old-blog/hello-world（不包含巢狀路徑）：

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/news/:slug', // 匹配的參數可用於目標路徑
        permanent: true,
      },
    ]
  },
}

萬用字元路徑匹配

要匹配萬用字元路徑，您可以在參數後使用 *，例如 /blog/:slug* 將匹配 /blog/a/b/c/d/hello-world：

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/blog/:slug*',
        destination: '/news/:slug*', // 匹配的參數可用於目標路徑
        permanent: true,
      },
    ]
  },
}

正則表達式路徑匹配

要匹配正則表達式路徑，您可以將正則表達式包裹在參數後的括號中，例如 /post/:slug(\\d{1,}) 將匹配 /post/123 但不匹配 /post/abc：

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        source: '/post/:slug(\\d{1,})',
        destination: '/news/:slug', // 匹配的參數可用於目標路徑
        permanent: false,
      },
    ]
  },
}

以下字符 (、)、{、}、:、*、+、? 用於正則表達式路徑匹配，因此當在 source 中作為非特殊值使用時，必須在它們前面加上 \\ 進行轉義：

next.config.js

module.exports = {
  async redirects() {
    return [
      {
        // 這將匹配請求 `/english(default)/something`
        source: '/english\\(default\\)/:slug',
        destination: '/en-us/:slug',
        permanent: false,
      },
    ]
  },
}

標頭、Cookie 和查詢匹配

要僅在標頭、Cookie 或查詢值也匹配 has 欄位或不匹配 missing 欄位時才匹配重新導向，可以使用 has 或 missing。必須同時匹配 source 和所有 has 項目，且所有 missing 項目都不匹配，才會應用重新導向。

has 和 missing 項目可以具有以下欄位：

type: String - 必須是 header、cookie、host 或 query 之一。
key: String - 要匹配的所選類型的鍵。
value: String 或 undefined - 要檢查的值，如果為 undefined，則匹配任何值。可以使用類似正則表達式的字串來捕獲值的特定部分，例如，如果值 first-(?<paramName>.*) 用於 first-second，則 second 可以在目標中使用 :paramName。

next.config.js

module.exports = {
  async redirects() {
    return [
      // 如果標頭 `x-redirect-me` 存在，
      // 將應用此重新導向
      {
        source: '/:path((?!another-page$).*)',
        has: [
          {
            type: 'header',
            key: 'x-redirect-me',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // 如果標頭 `x-dont-redirect` 存在，
      // 將不應用此重新導向
      {
        source: '/:path((?!another-page$).*)',
        missing: [
          {
            type: 'header',
            key: 'x-do-not-redirect',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
      // 如果來源、查詢和 Cookie 都匹配，
      // 將應用此重新導向
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // 由於提供了值且未使用命名捕獲組（例如 `(?<page>home)`），
            // 頁面值將不會在目標中可用
            value: 'home',
          },
          {
            type: 'cookie',
            key: 'authorized',
            value: 'true',
          },
        ],
        permanent: false,
        destination: '/another/:path*',
      },
      // 如果標頭 `x-authorized` 存在且包含匹配的值，
      // 將應用此重新導向
      {
        source: '/',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        permanent: false,
        destination: '/home?authorized=:authorized',
      },
      // 如果主機是 `example.com`，
      // 將應用此重新導向
      {
        source: '/:path((?!another-page$).*)',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        permanent: false,
        destination: '/another-page',
      },
    ]
  },
}

支援 basePath 的重新導向

當使用 basePath 支援進行重新導向時，每個 source 和 destination 會自動加上 basePath 前綴，除非您在重新導向中新增 basePath: false：

next.config.js

module.exports = {
  basePath: '/docs',

  async redirects() {
    return [
      {
        source: '/with-basePath', // 自動變為 /docs/with-basePath
        destination: '/another', // 自動變為 /docs/another
        permanent: false,
      },
      {
        // 由於設定了 basePath: false，不會新增 /docs
        source: '/without-basePath',
        destination: 'https://example.com',
        basePath: false,
        permanent: 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 redirects() {
    return [
      {
        source: '/with-locale', // 自動處理所有語言環境
        destination: '/another', // 自動傳遞語言環境
        permanent: false,
      },
      {
        // 由於設定了 locale: false，不會自動處理語言環境
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
        permanent: false,
      },
      {
        // 這匹配 '/' 因為 `en` 是 defaultLocale
        source: '/en',
        destination: '/en/another',
        locale: false,
        permanent: false,
      },
      // 即使設定了 locale: false，也可以匹配所有語言環境
      {
        source: '/:locale/page',
        destination: '/en/newpage',
        permanent: false,
        locale: false,
      },
      {
        // 這將轉換為 /(en|fr|de)/(.*)，因此不會匹配頂層
        // `/` 或 `/fr` 路由，像 /:path* 那樣
        source: '/(.*)',
        destination: '/another',
        permanent: false,
      },
    ]
  },
}

在某些罕見情況下，您可能需要為舊版 HTTP 客戶端分配自訂狀態碼以正確重新導向。在這些情況下，您可以使用 statusCode 屬性代替 permanent 屬性，但不能同時使用兩者。為了確保 IE11 相容性，會自動為 308 狀態碼新增 Refresh 標頭。

其他重新導向

在 API 路由和路由處理程式中，您可以根據傳入的請求進行重新導向。
在 getStaticProps 和 getServerSideProps 中，您可以在請求時重新導向特定頁面。

版本歷史

版本	變更
`v13.3.0`	新增 `missing`。
`v10.2.0`	新增 `has`。
`v9.5.0`	新增 `redirects`。

On this page