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*',
}

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（オプション）: ヘッダー、クエリパラメータ、クッキーなど特定のリクエスト要素の存在に基づく条件を指定
• 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) {
  // ミドルウェアロジックをここに記述
}

export function middleware(request) {
  // ミドルウェアロジックをここに記述
}

知っておくと便利:

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

NextResponse

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

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

ランタイム

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

バージョン履歴