middleware.js

middleware.js|ts 檔案用於編寫 中介軟體 (Middleware)，並在請求完成前於伺服器端執行程式碼。根據傳入的請求，您可以透過重寫、重新導向、修改請求或回應標頭，或直接回應來修改回應內容。

中介軟體會在路由渲染前執行，特別適用於實作自訂的伺服器端邏輯，例如身份驗證、日誌記錄或處理重新導向。

在專案根目錄中使用 middleware.ts (或 .js) 檔案來定義中介軟體。例如，與 app 或 pages 同層級，或放在 src 目錄中 (如果適用)。

import { NextResponse, NextRequest } from 'next/server'

// 若內部使用 `await`，此函式可標記為 `async`
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

import { NextResponse } from 'next/server'

// 若內部使用 `await`，此函式可標記為 `async`
export function middleware(request) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

匯出項目

中介軟體函式

檔案必須匯出單一函式，可以是預設匯出或命名為 middleware。請注意，不支援從同一個檔案匯出多個中介軟體。

// 預設匯出範例
export default function middleware(request) {
  // 中介軟體邏輯
}

設定物件 (選用)

可選地，可以與中介軟體函式一起匯出一個設定物件。此物件包含 matcher 來指定中介軟體適用的路徑。

Matcher

matcher 選項允許您指定中介軟體執行的特定路徑。您可以透過以下幾種方式指定這些路徑：

• 單一路徑：直接使用字串定義路徑，例如 '/about'。
• 多個路徑：使用陣列列出多個路徑，例如 matcher: ['/about', '/contact']，這會讓中介軟體同時套用於 /about 和 /contact。

此外，matcher 支援透過正則表達式指定複雜路徑，例如 matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)']，可精確控制要包含或排除的路徑。

matcher 選項也接受物件陣列，包含以下鍵值：

• source：用於匹配請求路徑的路徑或模式。可以是直接匹配路徑的字串，或用於更複雜匹配的模式。
• regexp (選用)：正則表達式字串，根據來源微調匹配。提供對包含或排除路徑的額外控制。
• locale (選用)：布林值，設為 false 時忽略基於地區設定的路由匹配。
• has (選用)：根據特定請求元素 (如標頭、查詢參數或 cookies) 的存在條件進行設定。
• missing (選用)：專注於某些請求元素缺失的條件，例如缺少標頭或 cookies。

export const config = {
  matcher: [
    {
      source: '/api/*',
      regexp: '^/api/(.*)',
      locale: false,
      has: [
        { type: 'header', key: 'Authorization', value: 'Bearer Token' },
        { type: 'query', key: 'userId', value: '123' },
      ],
      missing: [{ type: 'cookie', key: 'session', value: 'active' }],
    },
  ],
}

參數

request

定義中介軟體時，預設匯出函式接受單一參數 request。此參數是 NextRequest 的實例，代表傳入的 HTTP 請求。

import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // 中介軟體邏輯寫在這裡
}

export function middleware(request) {
  // 中介軟體邏輯寫在這裡
}

須知：

• NextRequest 是代表 Next.js 中介軟體中傳入 HTTP 請求的類型，而 NextResponse 是用於操作和發送回 HTTP 回應的類別。

NextResponse

中介軟體可以使用 NextResponse 物件，它擴展了 Web Response API。透過回傳 NextResponse 物件，您可以直接操作 cookies、設定標頭、實作重新導向和重寫路徑。

須知：對於重新導向，您也可以使用 Response.redirect 而非 NextResponse.redirect。

執行環境 (Runtime)

中介軟體預設使用 Edge 執行環境 (Edge runtime)。若不需要此設定，您可以使用 完整的 Node.js 執行環境 來執行中介軟體。

版本歷史