重新導向 (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 - 匹配時是否不包含語言環境 (locale)。
has 是一個包含 type、key 和 value 屬性的 has 物件陣列。
missing 是一個包含 type、key 和 value 屬性的 missing 物件陣列。

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

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

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

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

須知：請記得在 source 和 destination 路徑參數中的冒號 : 前包含正斜線 /，否則路徑將被視為字串字面值，可能導致無限重新導向。

當請求 /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-second 使用值 first-(?<paramName>.*)，則 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），
            // page 值將不會在目標中可用
            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 路由和路由處理程式 (Route Handlers) 中，您可以根據傳入的請求進行重新導向。
在 getStaticProps 和 getServerSideProps 中，您可以在請求時重新導向特定頁面。

版本歷史

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

On this page