middleware.js

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

中介軟體會在路由渲染之前執行。它對於實現自訂伺服器端邏輯（例如驗證、記錄或處理重新導向）特別有用。

使用專案根目錄中的 middleware.ts（或 .js）檔案來定義中介軟體。例如，與 app 或 pages 位於同一層級，或者如果有的話，在 src 資料夾內。

import { NextResponse, NextRequest } from 'next/server'
 
// This function can be marked `async` if using `await` inside
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
export const config = {
  matcher: '/about/:path*',
}

匯出

中介軟體函式

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

// Example of default export
export default function middleware(request) {
  // Middleware logic
}

設定物件 (選用)

（選用）可以與中介軟體函式一起匯出一個設定物件。此物件包含用於指定中介軟體應用路徑的 matcher。

Matcher（匹配器）

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

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

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

matcher 選項也接受具有以下鍵值的物件陣列：

• source：用於匹配請求路徑的路徑或模式。它可以是字串，用於直接路徑匹配，也可以是模式，用於更複雜的匹配。
• regexp（選用）：一個正規表達式字串，根據來源微調匹配。它提供了對包含或排除哪些路徑的額外控制。
• locale（選用）：一個布林值，設定為 false 時，會在路徑匹配中忽略基於地區的路由。
• has（選用）：根據特定請求元素（例如標頭、查詢參數或 Cookie）的存在與否指定條件。
• missing（選用）：著重於缺少某些請求元素的條件，例如缺少標頭或 Cookie。

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) {
  // Middleware logic goes here
}

注意事項:

• NextRequest 是一種表示 Next.js 中間件中傳入 HTTP 請求的類型，而 NextResponse 是一個用於操作和發送回 HTTP 回應的類別。

NextResponse

中間件可以使用 NextResponse 物件，該物件繼承了 Web Response API。透過返回 NextResponse 物件，您可以直接操作 Cookie、設定標頭、實作重新導向和重寫路徑。

注意事項：對於重新導向，您也可以使用 Response.redirect 取代 NextResponse.redirect。

執行環境。無法使用 Node.js 執行環境。

版本歷史記錄