Next.jsのMiddleware実例:proxy.ts対応版
Next.js Middleware(Proxy)の実例
Next.js Middlewareの実例(現在はproxy.ts):認証、地域、A/B | We.Inc
Next.js 16でmiddleware.tsに代わったproxy.tsの実例集。認証リダイレクト、国別ルーティング、A/Bテスト用クッキー、言語判定、matcher、シミュレーターを用意しています。
Next.js 16では、Middlewareのファイル名はproxy.tsになり、proxyという名前の関数をエクスポートします。middleware.tsは非推奨となり、コードモッドで名前を変更できます。この関数はNextRequestを受け取り、リダイレクト、リライト、ヘッダーやクッキーの設定、レスポンスの返却を行えます。config.matcherで実行するパスを制限します。現在はデフォルトでNode.jsランタイムを使います。
Next.js 16での変更点
- 以前(15以前)
- 現在(16)
- proxy.ts、appまたはpagesと同じ階層に置く
- export function middleware()
- export function proxy() またはデフォルトエクスポート
- デフォルトはEdgeランタイム
- デフォルトはNode.jsランタイム。ランタイムオプションを指定するとエラーになる
- skipMiddlewareUrlNormalize
- skipProxyUrlNormalize
- 手動で名前を変更
- npx @next/コードモッド@canary middleware-to-proxy .
ネット上の回答の多くは、いまだにEdgeランタイムで動くmiddleware.tsを説明しています。ここで紹介する例は現在のファイル名を使い、そのまま動作し、応用しやすい短さに収めています。デプロイ前にシミュレーターを試せば、複数の処理を組み合わせたproxyのどの分岐が、特定のリクエストで実行されるかを確認できます。
- パスを選び、仮のリクエストに含めるクッキー、国、言語を設定します。
- シミュレーターは、下にある認証、国、A/B、言語の例を、この順番でブラウザー内で適用します。
- 結果を確認します。そのまま通過、新しいURLへのリダイレクト、または非公開ルートへのリライトのいずれかです。
- 自分のケースに合う例をコピーして、パスを調整します。
- matcherがないと、proxyは_next/staticのファイルや画像を含むすべてのリクエストで実行されます。これらを除外しないと、ログインのリダイレクトがCSSまでブロックしてしまうことがあります。
- matcherの値は定数でなければなりません。matcherはビルド時に読み込まれるため、変数は無視されるとドキュメントに書かれています。
- proxyでのチェックは楽観的なものにとどめましょう。クッキーを読み、なければリダイレクトし、本当の権限チェックはデータの近くで行います。
- ページにデータを渡すには、NextResponse.next({ request: { headers } })でリクエストヘッダーを設定します。トップレベルでヘッダーを渡すと、代わりにブラウザーへ送られてしまいます。
- next/experimental/testing/serverの実験的なヘルパーunstable_doesProxyMatchを使うと、matcherの単体テストができます。
よくある質問
Next.jsのMiddlewareは非推奨になったのですか?
非推奨になったのは名前です。バージョン16ではMiddlewareのファイル規約が非推奨となり、同じリクエストとレスポンスのAPIのままproxyに名前が変わりました。古いmiddleware.tsは移行することが想定されており、公式のコードモッドがファイル名とエクスポートする関数名の両方を変更します。
なぜproxyに名前が変わったのですか?
Next.jsチームによると、Middlewareという言葉がExpressのMiddlewareと混同され、使いすぎを招いていたためです。Proxyはアプリの手前にあるネットワークの境界を表す言葉で、ほかに適したAPIがない場合の最後の手段として使うよう推奨されています。
proxy.tsでEdgeランタイムを使えますか?
使えません。ProxyのデフォルトはNode.jsで、proxyファイルでランタイムのセグメントオプションを設定するとエラーになります。その代わり、Node.js専用のライブラリが使えるようになりました。これは、Edge専用だった以前のMiddlewareに対するよくある不満でした。
認証はproxyで行うべきですか?
最初のフィルターとしてだけ使いましょう。Next.jsの認証ガイドでは、すばやくリダイレクトするためにproxyでセッションクッキーを読み、データアクセス層、Server Actions、Route Handlersでもう一度セッションを検証するよう推奨しています。matcherで除外されたServer Functionsは、proxyを完全に素通りします。
静的エクスポートでもproxyは動きますか?
動きません。実行するサーバーがないため、ドキュメントのプラットフォーム表では静的エクスポートは非対応とされています。Node.jsサーバーとDockerは対応しており、ほかのホスティングはアダプター次第です。
リクエストの中でのproxyの位置
- Next.jsは、まずnext.configのヘッダーとリダイレクトの設定を適用し、次にproxyを実行し、その後beforeFilesのリライト、実際のファイルとルートの順に処理します。そのため、next.configのリダイレクトは、proxyのコードがリクエストを受け取る前に優先されます。
- proxyは、リダイレクトやJSONレスポンスを返して自らリクエストを終わらせることも、ヘッダーやクッキーを追加しながらNextResponse.next()で処理を続行させることもできます。
リダイレクトかリライトか
- リダイレクトはアドレスバーを変更し、訪問者に余分な往復を1回発生させます。ログアウト中のユーザーを/loginに送る場合など、URLそのものを変えるべきときに使いましょう。
- リライトは、アドレスバーをそのままにして別のルートを返します。A/Bテストや国別のバリエーションのように、両方のバージョンで1つの公開URLを共有したい場合に向いています。
処理は軽く保つ
- proxyはページ表示だけでなくプリフェッチでも実行されることがあるため、ここでのデータベース呼び出しはすぐに膨れ上がります。クッキーやヘッダーを読むのは軽い処理ですが、毎回のリクエストでユーザーテーブルを検索するのは重い処理です。
- ログ記録などのバックグラウンド処理はevent.waitUntil()に入れられます。これにより、レスポンス送信後も処理が継続されます。
matcherのパターン
config.matcherのパスの動き
- パターン
- 一致するもの
- 一致しないもの
- すべてのページ
- APIルート、ビルド成果物、ファビコン
proxy.tsの例
ログアウト中の訪問者をリダイレクトする
楽観的なチェックです。セッションクッキーの有無だけを確認し、訪問者が向かっていた先を記憶します。
リライトによる国別ルーティング
訪問者のURLは/pricingのままで、EU向けページが表示されます。ここで使っている国のヘッダーはVercelが付与するものです。ほかのホスティングでは独自のヘッダー名を使います。
固定クッキーを使ったA/Bテスト
訪問者は一度だけグループに割り当てられ、クッキーによってそのグループにとどまり、リライトによって同じURLでバリエーションが表示されます。
訪問者を自分の言語のページへ送る
すでに対応ロケールで始まるパスはそのまま通過します。それ以外は、Accept-Languageで最初に一致した言語を使ってリダイレクトされます。
リクエストヘッダーでページに値を渡す
requestオプションの中でヘッダーを設定すると、ブラウザーに公開することなく、ルート側でheaders()を使って読み取れます。
認証の例:保護されたパスで、セッションクッキーがありません。
国の例:{country}はEUの一覧に含まれるため、同じURLでEU向けページが表示されます。
A/Bの例:訪問者はグループ{bucket}に属し、クッキーによってそのまま維持されます。
言語のmatcherで除外されているため、リクエストはそのまま続行されます。
言語の例:パスにすでに対応ロケールが含まれています。
言語の例:ヘッダー内で最初に対応している言語は{locale}です。
Proxyシミュレーター
パス、セッションクッキー、国、ブラウザーの言語を設定すると、下の例がリクエストを通過させるか、リダイレクトするか、リライトするかを確認できます。
リクエストのパス
国のヘッダー(x-vercel-ip-country)
Accept-Languageヘッダー
A/Bのクッキーグループ
リクエストにセッションクッキーがある
無料でサイトを作る · 無料で構築、カード登録不要
関連: ガイド|Webマーケティングと集客を学ぶ
- Next.js SEOチェックリスト(App Router)
- Next.jsとNode.jsの違い:両者の関係を解説
- Next.js vs React:Nextが加えるものと必要になる場面
- Nginx 502 Bad Gatewayと、よく出る他の4つのエラー
- nginxのロードバランシング:upstream、方式、ヘルスチェック
- ノーコード AI エージェントビルダー:選ぶためのスコアカード
- noindexタグ:ページをGoogleから正しく除外する方法
- Notion APIキー:作成、ページ共有、最初のリクエスト
製品
- AI ホームページ作成ツール:作りたいサイトを普段の言葉で伝えるだけで、数分で公開
- ホワイトラベル プラットフォーム:自社ブランド、自社ドメイン、自社の利益で運営
- エンタープライズ:SSO、個別の SLA、専任サポート
- 開発者向け API:自社の SaaS にサイト生成機能を組み込み
ご利用いただける方
- 制作会社・代理店向け:自社ブランドで再販
- フリーランス向け:自分ブランドのビルダーを持つ
- ホスティング事業者向け:サービスにビルダーを追加
- SaaS プラットフォーム向け:API でサイト作成を組み込み
- スタートアップ向け
- 金融サービス向け
- 医療・ヘルスケア向け
機能
リソース
- ブログ
- ヘルプセンター
- 無料ビジネスツール
- ホームページ テンプレート
- テンプレート集
- サイト事例
- ガイド
- 比較
- 代替サービス
- おすすめ
- レビュー
- 料金ガイド
- 用語集・ガイド
- 連携サービス
- 開発者向け
- ベンチマーク
- Windows アプリ