ミドルウェア
ミドルウェアを使用すると、リクエストが完了する前にコードを実行できます。そして、受信したリクエストに基づいて、レスポンスを書き換えたり、リダイレクトしたり、リクエストやレスポンスのヘッダーを変更したり、直接レスポンスを返したりできます。
ミドルウェアはキャッシュされたコンテンツやルートがマッチングされる前に実行されます。詳細はパスマッチングを参照してください。
ユースケース
ミドルウェアが効果的な一般的なシナリオ:
- 受信リクエストの一部を読み取った後のクイックリダイレクト
- A/Bテストや実験に基づいて異なるページに書き換え
- すべてのページまたは一部のページのヘッダーを変更
ミドルウェアが適さないケース:
- 遅いデータフェッチ
- セッション管理
規約
プロジェクトのルートにmiddleware.ts
(または.js
)ファイルを使用してミドルウェアを定義します。例えば、pages
やapp
と同じレベル、またはsrc
内(該当する場合)。
注: プロジェクトごとに1つの
middleware.ts
ファイルしかサポートされていませんが、ミドルウェアロジックをモジュール化して整理することは可能です。ミドルウェア機能を個別の.ts
または.js
ファイルに分割し、メインのmiddleware.ts
ファイルにインポートします。これにより、ルート固有のミドルウェアをクリーンに管理し、middleware.ts
で集中制御できます。単一のミドルウェアファイルを強制することで、設定が簡素化され、潜在的な競合が防止され、複数のミドルウェアレイヤーを回避することでパフォーマンスが最適化されます。
例
パスマッチング
ミドルウェアはプロジェクト内のすべてのルートに対して呼び出されます。このため、特定のルートを正確にターゲットまたは除外するためにマッチャーを使用することが重要です。実行順序は次のとおりです:
next.config.js
のheaders
next.config.js
のredirects
- ミドルウェア(
rewrites
、redirects
など) next.config.js
のbeforeFiles
(rewrites
)- ファイルシステムルート(
public/
、_next/static/
、pages/
、app/
など) next.config.js
のafterFiles
(rewrites
)- ダイナミックルート(
/blog/[slug]
) next.config.js
のfallback
(rewrites
)
ミドルウェアが実行されるパスを定義する方法は2つあります:
マッチャー
matcher
を使用すると、特定のパスでミドルウェアを実行するようにフィルタリングできます。
単一のパスまたは複数のパスを配列構文でマッチできます:
matcher
設定では完全な正規表現が可能なので、否定先読みや文字マッチングなどのマッチングがサポートされています。特定のパスを除くすべてにマッチする否定先読みの例は次のとおりです:
missing
またはhas
配列、またはその組み合わせを使用して、特定のリクエストに対してミドルウェアをバイパスすることもできます:
知っておくと良い:
matcher
の値はビルド時に静的に解析できるように定数である必要があります。変数などの動的な値は無視されます。
設定されたマッチャー:
/
で始まる必要がある- 名前付きパラメータを含めることができる:
/about/:path
は/about/a
と/about/b
にマッチするが/about/a/c
にはマッチしない - 名前付きパラメータに修飾子を付けられる(
:
で始まる):/about/:path*
は*
が_ゼロ以上_なので/about/a/b/c
にマッチする。?
は_ゼロまたは1つ_、+
は_1つ以上_ - 括弧で囲まれた正規表現を使用できる:
/about/(.*)
は/about/:path*
と同じ
詳細はpath-to-regexpドキュメントを参照してください。
知っておくと良い: 後方互換性のため、Next.jsは常に
/public
を/public/index
として扱います。したがって、/public/:path
のマッチャーはマッチします。
条件文
NextResponse
NextResponse
APIを使用すると、次のことができます:
- 受信リクエストを別のURLに
redirect
する - 指定されたURLを表示してレスポンスを
rewrite
する - APIルート、
getServerSideProps
、rewrite
先のリクエストヘッダーを設定する - レスポンスのクッキーを設定する
- レスポンスヘッダーを設定する
ミドルウェアからレスポンスを生成するには、次のいずれかを行います:
- レスポンスを生成するルート(PageまたはEdge API Route)に
rewrite
する NextResponse
を直接返す。レスポンスの生成を参照
クッキーの使用
クッキーは通常のヘッダーです。Request
ではCookie
ヘッダーに、Response
ではSet-Cookie
ヘッダーに格納されます。Next.jsは、NextRequest
とNextResponse
のcookies
拡張機能を通じてこれらのクッキーにアクセスして操作する便利な方法を提供します。
- 受信リクエストの場合、
cookies
には次のメソッドがあります:get
、getAll
、set
、delete
。has
でクッキーの存在を確認したり、clear
ですべてのクッキーを削除したりできます。 - 送信レスポンスの場合、
cookies
には次のメソッドがあります:get
、getAll
、set
、delete
。
ヘッダーの設定
NextResponse
APIを使用してリクエストとレスポンスのヘッダーを設定できます(_リクエスト_ヘッダーの設定はNext.js v13.0.0以降で利用可能)。
知っておくと良い: バックエンドのWebサーバー設定によっては、大きなヘッダーを設定すると431 Request Header Fields Too Largeエラーが発生する可能性があるため、避けてください。
CORS
ミドルウェアでCORSヘッダーを設定して、シンプルおよびプリフライトリクエストを含むクロスオリジンリクエストを許可できます。
レスポンスの生成
ミドルウェアから直接、Response
または NextResponse
インスタンスを返すことでレスポンスを生成できます。(これは Next.js v13.1.0 以降で利用可能)
waitUntil
と NextFetchEvent
NextFetchEvent
オブジェクトはネイティブの FetchEvent
オブジェクトを拡張し、waitUntil()
メソッドを含みます。
waitUntil()
メソッドはプロミスを引数に取り、そのプロミスが解決するまでミドルウェアのライフタイムを延長します。これはバックグラウンドで作業を実行するのに便利です。
高度なミドルウェアフラグ
Next.jsの v13.1
では、高度なユースケースに対応するため、skipMiddlewareUrlNormalize
と skipTrailingSlashRedirect
の2つの追加フラグがミドルウェアに導入されました。
skipTrailingSlashRedirect
は、末尾のスラッシュを追加または削除するNext.jsのリダイレクトを無効にします。これにより、ミドルウェア内でカスタム処理を行い、一部のパスでは末尾のスラッシュを維持し、他のパスでは維持しないといったことが可能になり、段階的な移行が容易になります。
skipMiddlewareUrlNormalize
を使用すると、Next.jsのURL正規化を無効にし、直接訪問とクライアント遷移を同じように処理できます。高度なケースでは、このオプションにより元のURLを使用して完全な制御が可能になります。
ユニットテスト(実験的機能)
Next.js 15.1以降、next/experimental/testing/server
パッケージにはミドルウェアファイルのユニットテストを支援するユーティリティが含まれています。ミドルウェアのユニットテストを行うことで、コードが本番環境に到達する前に、目的のパスでのみ実行されることや、カスタムルーティングロジックが意図した通りに動作することを確認できます。
unstable_doesMiddlewareMatch
関数を使用して、提供されたURL、ヘッダー、クッキーに対してミドルウェアが実行されるかどうかをアサートできます。
ミドルウェア関数全体をテストすることも可能です。
ランタイム
ミドルウェアはデフォルトでEdgeランタイムを使用します。v15.2(canary)以降、Node.jsランタイムを使用する実験的サポートが追加されました。有効にするには、next.config
ファイルにフラグを追加します:
そして、ミドルウェアファイルで config
オブジェクト内のランタイムを nodejs
に設定します:
注記: この機能はまだ本番環境での使用を推奨していません。そのため、Next.jsは安定版リリースではなくnext@canaryリリースを使用している場合を除き、エラーをスローします。
プラットフォームサポート
デプロイオプション | サポート状況 |
---|---|
Node.jsサーバー | 対応 |
Dockerコンテナ | 対応 |
静的エクスポート | 非対応 |
アダプター | プラットフォーム依存 |
Next.jsをセルフホスティングする際のミドルウェア設定方法を参照してください。
バージョン履歴
バージョン | 変更内容 |
---|---|
v15.2.0 | ミドルウェアでNode.jsランタイムが使用可能に(実験的) |
v13.1.0 | 高度なミドルウェアフラグが追加 |
v13.0.0 | ミドルウェアがリクエストヘッダー、レスポンスヘッダーの変更とレスポンス送信が可能に |
v12.2.0 | ミドルウェアが安定版に、アップグレードガイドを参照 |
v12.0.9 | Edge Runtimeで絶対URLが必須に(PR) |
v12.0.0 | ミドルウェア(ベータ)が追加 |