middleware.js

middleware.js|ts ファイルは、ミドルウェアを記述し、リクエストが完了する前にサーバー上でコードを実行するために使用されます。次に、受信リクエストに基づいて、リライト、リダイレクト、リクエストまたはレスポンスヘッダーの変更、または直接応答によってレスポンスを変更できます。

ミドルウェアは、ルートがレンダリングされる前に実行されます。認証、ログ記録、リダイレクト処理などのカスタムサーバーサイドロジックの実装に特に役立ちます。

プロジェクトのルートにあるファイル 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
}

config オブジェクト (オプション)

オプションで、ミドルウェア関数と一緒に config オブジェクトをエクスポートできます。このオブジェクトには、ミドルウェアが適用されるパスを指定するためのマッチャーが含まれています。

マッチャー

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 を受け入れます。このパラメーターは、受信 HTTP リクエストを表す NextRequest のインスタンスです。

import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  // Middleware logic goes here
}

知っておくと便利:

• NextRequest は Next.js ミドルウェアの受信 HTTP リクエストを表す型であり

NextResponse

ミドルウェアでは、NextResponse オブジェクトを使用できます。これは Web Response API を拡張したものです。NextResponse オブジェクトを返すことで、Cookieの直接的な操作、ヘッダーの設定、リダイレクトの実装、パスのリライトが可能です。

知っておくと良いこと: リダイレクトには、NextResponse.redirect の代わりに Response.redirect を使用することもできます。

ランタイム

ミドルウェアは Edge ランタイム のみをサポートしています。Node.js ランタイムは使用できません。

バージョン履歴