middleware.js

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

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

プロジェクトのルートに 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*',
}

エクスポート

ミドルウェア関数

ファイルは単一の関数をデフォルトエクスポートまたは middleware という名前でエクスポートする必要があります。同じファイルから複数のミドルウェアをエクスポートすることはサポートされていません。

// デフォルトエクスポートの例
export default function middleware(request) {
  // ミドルウェアロジック
}

設定オブジェクト（オプション）

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

マッチャー

matcher オプションを使用すると、ミドルウェアを実行する特定のパスをターゲットにできます。これらのパスはいくつかの方法で指定できます：

• 単一のパス：'/about' のように文字列で直接パスを定義
• 複数のパス：matcher: ['/about', '/contact'] のように配列を使用して複数のパスをリストアップ

さらに、matcher は正規表現を使用した複雑なパス指定もサポートしています。例えば matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'] のように、含めるまたは除外するパスを精密に制御できます。

matcher オプションは以下のキーを持つオブジェクトの配列も受け入れます：

• source: リクエストパスとマッチさせるパスまたはパターン。直接パスマッチングの場合は文字列、より複雑なマッチングの場合はパターン
• regexp (オプション): ソースに基づいてマッチングを微調整する正規表現文字列
• locale (オプション): false に設定すると、ロケールベースのルーティングを無視
• has (オプション): ヘッダー、クエリパラメータ、クッキーなどの特定のリクエスト要素の存在に基づく条件
• missing (オプション): ヘッダーやクッキーなど特定のリクエスト要素が欠如している条件

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) {
  // ミドルウェアロジック
}

知っておくと便利:

• NextRequest は Next.js ミドルウェアにおける受信 HTTP リクエストを表す型で、NextResponse は HTTP レスポンスを操作して返すために使用されるクラスです。

NextResponse

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

知っておくと便利: リダイレクトには NextResponse.redirect の代わりに Response.redirect も使用できます。

ランタイム

ミドルウェアはデフォルトでEdge ランタイムを使用します。これを使用したくない場合は、完全な Node.js ランタイムを使用してミドルウェアを実行できます。

バージョン履歴