メインコンテンツまでスキップ

Middleware

Middlewareは、リクエストが完了する前にコードを実行することができます。その後、受信リクエストに基づいて、レスポンスをリライト、リダイレクト、リクエストやレスポンスヘッダーを変更、または直接応答することによって修正することができます。

Middlewareはキャッシュされたコンテンツやルートが一致する前に実行されます。詳細はMatching Pathsを参照してください。

ユースケース​

アプリケーションにMiddlewareを統合することにより、パフォーマンス、セキュリティ、およびユーザーエクスペリエンスに大きな改善をもたらすことができます。Middlewareが特に効果的な一般的なシナリオには以下が含まれます：

  • 認証と認可：特定のページやAPIルートへのアクセスを許可する前に、ユーザーのIDを確認し、セッションcookieを確認します
  • サーバーサイドリダイレクト：特定の条件（例：ロケール、ユーザーロール）に基づいて、サーバーレベルでユーザーをリダイレクトします
  • パスのリライト：A/Bテストや機能の展開、または古いパスをサポートするために、リクエストプロパティに基づいて動的にAPIルートやページへのパスをリライトします
  • ボット検出：ボットトラフィックを検出してブロックすることにより、リソースを保護します
  • ロギングと分析：ページやAPIが処理する前に、インサイトのためのリクエストデータをキャプチャおよび分析します
  • 機能フラグ：シームレスな機能の展開やテストのために、動的に機能を有効/無効にします

Middlewareが最適でない状況を認識することも非常に重要です。以下のようなシナリオには注意が必要です：

  • 複雑なデータのフェッチと操作：Middlewareは直接データをフェッチまたは操作するために設計されていないため、これはRoute Handlersまたはサーバーサイドユーティリティ内で行うべきです
  • 重い計算タスク：Middlewareは軽量で迅速に応答する必要があり、ページの読み込みを遅らせる可能性があります。重い計算タスクや長時間実行プロセスは専用のRoute Handlers内で行うべきです
  • 広範なセッション管理：Middlewareは基本的なセッションタスクを管理できますが、広範なセッション管理は専用の認証サービスまたはRoute Handlers内で管理すべきです
  • 直接的なデータベース操作：Middleware内で直接的なデータベース操作を行うことは推奨されません。データベースの操作はRoute Handlersまたはサーバーサイドユーティリティ内で行うべきです

規約​

プロジェクトのrootにファイルmiddleware.ts（または.js）を使用してMiddlewareを定義してください。例えば、pagesやappと同じレベル、または場合によってはsrcの中に配置します。

注意：プロジェクトごとにサポートされるmiddleware.tsファイルは1つだけですが、それでもモジュール式にミドルウェアロジックを整理できます。異なる.tsまたは.jsファイルにミドルウェア機能を分けて、メインのmiddleware.tsファイルにインポートします。これにより、ルート固有のミドルウェアをクリーンに管理し、middleware.tsに集約して中央で制御できます。単一のミドルウェアファイルを強制することで、設定が簡素化され、潜在的な競合を防ぎ、複数のミドルウェア層を避けることでパフォーマンスが向上します。

例​

middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// `await`を内部で使用する場合、この関数は`async`としてマークできます
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// 詳細については以下の"Matching Paths"を参照してください
export const config = {
  matcher: '/about/:path*',
}

パスを一致させる​

あなたのプロジェクト内のすべてのルートに対してMiddlewareが呼び出されます。これを考慮すると、特定のルートを正確にターゲットまたは除外するためにマッチャーを使用することが重要です。実行順序は以下の通りです：

  1. next.config.jsのheaders
  2. next.config.jsのredirects
  3. ミドルウェア（rewrites、redirectsなど）
  4. next.config.jsのbeforeFiles (rewrites)
  5. ファイルシステムルート (public/, _next/static/, pages/, app/, etc.)
  6. next.config.jsのafterFiles (rewrites)
  7. 動的ルート (/blog/[slug])
  8. next.config.jsのfallback (rewrites)

Middlewareがどのパスで実行されるかを定義する方法は2つあります：

  1. カスタムマッチャー設定
  2. 条件文

マッチャー​

matcherを使用して、特定のパスでMiddlewareを実行するようフィルタリングできます。

middleware.js
export const config = {
  matcher: '/about/:path*',
}

単一のパスをマッチさせることも、配列構文を使用して複数のパスをマッチさせることもできます：

middleware.js
export const config = {
  matcher: ['/about/:path*', '/dashboard/:path*'],
}

matcher設定では、完全な正規表現が可能なので、否定の先読みや文字のマッチングなどがサポートされています。特定のパスを除くすべてにマッチする否定の先読みの例は以下の通りです：

middleware.js
export const config = {
  matcher: [
    /*
     * 以下で始まるもの以外のすべてのリクエストパスにマッチ：
     * - api (APIルート)
     * - _next/static (静的ファイル)
     * - _next/image (画像最適化ファイル)
     * - favicon.ico, sitemap.xml, robots.txt (メタデータファイル)
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
}

または、missingやhas配列、またはその両方の組み合わせを使用して、特定のリクエストをMiddlewareからバイパスすることもできます：

middleware.js
export const config = {
  matcher: [
    /*
     * 以下で始まるもの以外のすべてのリクエストパスにマッチ：
     * - api (APIルート)
     * - _next/static (静的ファイル)
     * - _next/image (画像最適化ファイル)
     * - favicon.ico, sitemap.xml, robots.txt (メタデータファイル)
     */
    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },

    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      has: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },

    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      has: [{ type: 'header', key: 'x-present' }],
      missing: [{ type: 'header', key: 'x-missing', value: 'prefetch' }],
    },
  ],
}

Good to know: matcherの値は、ビルド時に静的に解析されるように定数である必要があります。変数などの動的な値は無視されます。

構成されたマッチャー：

  1. /で始まらなければなりません
  2. ネームドパラメータを含めることができます： /about/:pathは/about/aや/about/bにマッチしますが、/about/a/cにはマッチしません
  3. ネームドパラメータに修飾子を使用できます（: で始まる）：/about/:path*は/about/a/b/cにマッチします。*は0回以上を示します。?は0か1回、 +は1回以上を示します
  4. 括弧で囲んだ正規表現を使用できます：/about/(.*)は/about/:path*と同じです

詳細はpath-to-regexpのドキュメントを参照してください。

Good to know: 後方互換性のために、Next.jsは常に/publicを/public/indexとして考慮するため、/public/:pathのマッチャーはマッチします。

条件文​

middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/about')) {
    return NextResponse.rewrite(new URL('/about-2', request.url))
  }

  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.rewrite(new URL('/dashboard/user', request.url))
  }
}

NextResponse​

NextResponse APIを使用すると以下のことができます：

  • 受信リクエストを異なるURLにredirectする
  • 指定されたURLを表示してレスポンスをrewriteする
  • リクエストヘッダーをAPIルート、getServerSideProps、およびrewriteの宛先に設定する
  • レスポンスcookieを設定する
  • レスポンスヘッダーを設定する

Middlewareからレスポンスを生成するには、次のことができます：

  1. レスポンスを生成するルート（Page または Route Handler）にrewriteする
  2. NextResponseを直接返す。詳細はレスポンスを生成を参照してください

Cookiesを使用する​

Cookiesは通常のヘッダーです。Requestでは、Cookieヘッダーに格納されています。Responseでは、Set-Cookieヘッダーにあります。Next.jsは、NextRequestとNextResponseのcookies拡張を通じて、これらのcookieにアクセスし操作するための便利な方法を提供します。

  1. 受信リクエストの場合、cookiesには次のメソッド：get、getAll、set、deleteがあります。hasでcookieの存在を確認することも、clearですべてのクッキーを削除することもできます
  2. 発信レスポンスの場合、cookiesにはget、getAll、set、deleteというメソッドがあります
middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // 着信リクエストには"Cookie:nextjs=fast"ヘッダーがあると仮定します
  // `RequestCookies` APIを使用してリクエストからcookieを取得する
  let cookie = request.cookies.get('nextjs')
  console.log(cookie) // => { name: 'nextjs', value: 'fast', Path: '/' }
  const allCookies = request.cookies.getAll()
  console.log(allCookies) // => [{ name: 'nextjs', value: 'fast' }]

  request.cookies.has('nextjs') // => true
  request.cookies.delete('nextjs')
  request.cookies.has('nextjs') // => false

  // `ResponseCookies` APIを使用してレスポンスにcookieを設定する
  const response = NextResponse.next()
  response.cookies.set('vercel', 'fast')
  response.cookies.set({
    name: 'vercel',
    value: 'fast',
    path: '/',
  })
  cookie = response.cookies.get('vercel')
  console.log(cookie) // => { name: 'vercel', value: 'fast', Path: '/' }
  // 出力されるレスポンスは`Set-Cookie:vercel=fast;path=/`ヘッダーを持ちます

  return response
}

ヘッダーの設定​

NextResponse APIを使用してリクエストおよびレスポンスヘッダーを設定できます（リクエスト ヘッダーの設定はNext.js v13.0.0から利用可能です）。

middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // リクエストヘッダーを複製し、新しいヘッダー`x-hello-from-middleware1`を設定します
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-hello-from-middleware1', 'hello')

  // NextResponse.nextでリクエストヘッダーを設定できます
  const response = NextResponse.next({
    request: {
      // 新しいリクエストヘッダー
      headers: requestHeaders,
    },
  })

  // 新しいレスポンスヘッダー`x-hello-from-middleware2`を設定します
  response.headers.set('x-hello-from-middleware2', 'hello')
  return response
}

Good to know: 大きなヘッダーを設定すると、バックエンドWebサーバーの設定によっては431 Request Header Fields Too Largeエラーを引き起こす可能性があるので避けてください。

CORS​

MiddlewareでCORSヘッダーを設定して、シンプルおよびプレフライトリクエストを含むクロスオリジンリクエストを許可できます。

middleware.ts
import { NextRequest, NextResponse } from 'next/server'

const allowedOrigins = ['https://acme.com', 'https://my-app.org']

const corsOptions = {
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
}

export function middleware(request: NextRequest) {
  // リクエストからオリジンを確認します
  const origin = request.headers.get('origin') ?? ''
  const isAllowedOrigin = allowedOrigins.includes(origin)

  // プレフライトリクエストを処理します
  const isPreflight = request.method === 'OPTIONS'

  if (isPreflight) {
    const preflightHeaders = {
      ...(isAllowedOrigin && { 'Access-Control-Allow-Origin': origin }),
      ...corsOptions,
    }
    return NextResponse.json({}, { headers: preflightHeaders })
  }

  // シンプルなリクエストを処理します
  const response = NextResponse.next()

  if (isAllowedOrigin) {
    response.headers.set('Access-Control-Allow-Origin', origin)
  }

  Object.entries(corsOptions).forEach(([key, value]) => {
    response.headers.set(key, value)
  })

  return response
}

export const config = {
  matcher: '/api/:path*',
}

Good to know: Route Handlersで個々のルートに対してCORSヘッダーを設定できます。

レスポンスを生成する​

MiddlewareからResponseまたはNextResponseインスタンスを返すことにより、直接応答することができます。（これはNext.js v13.1.0以降で利用可能です）

middleware.ts
import type { NextRequest } from 'next/server'
import { isAuthenticated } from '@lib/auth'

// Middlewareを`/api/`で始まるパスに制限します
export const config = {
  matcher: '/api/:function*',
}

export function middleware(request: NextRequest) {
  // リクエストをチェックするために認証関数を呼び出します
  if (!isAuthenticated(request)) {
    // エラーメッセージを示すJSONで応答します
    return Response.json(
      { success: false, message: 'authentication failed' },
      { status: 401 }
    )
  }
}

waitUntilとNextFetchEvent​

NextFetchEventオブジェクトはネイティブのFetchEventオブジェクトを拡張しており、waitUntil()メソッドを含んでいます。

waitUntil()メソッドはPromiseを引数に取り、そのPromiseが解決するまでMiddlewareの寿命を延ばします。これはバックグラウンドで作業を行うために役立ちます。

middleware.ts
import { NextResponse } from 'next/server'
import type { NextFetchEvent, NextRequest } from 'next/server'

export function middleware(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  )

  return NextResponse.next()
}

高度なミドルウェアフラグ​

Next.jsのv13.1で、skipMiddlewareUrlNormalizeとskipTrailingSlashRedirectというMiddlewareの2つの追加フラグが導入され、複雑なユースケースの処理が可能になりました。

skipTrailingSlashRedirectは、末尾のスラッシュを追加または削除するためのNext.jsによるリダイレクトを無効にします。これにより、一部のパスには末尾スラッシュを維持し、他のパスには末尾スラッシュを適用するカスタムハンドリングが可能になり、インクリメンタルな移行が容易になります。

next.config.js
module.exports = {
  skipTrailingSlashRedirect: true,
}
middleware.js
const legacyPrefixes = ['/docs', '/blog']

export default async function middleware(req) {
  const { pathname } = req.nextUrl

  if (legacyPrefixes.some((prefix) => pathname.startsWith(prefix))) {
    return NextResponse.next()
  }

  // 末尾のスラッシュの取り扱いを適用する
  if (
    !pathname.endsWith('/') &&
    !pathname.match(/((?!\.well-known(?:\/.*)?)(?:[^/]+\/)*[^/]+\.\w+)/)
  ) {
    return NextResponse.redirect(
      new URL(`${req.nextUrl.pathname}/`, req.nextUrl)
    )
  }
}

skipMiddlewareUrlNormalizeは、Next.jsでのURL正規化の無効化を許可し、直接訪問とクライアント遷移の取り扱いを同じにします。一部の高度なケースでは、このオプションを使用することで元のURLを使用することで完全な制御が可能になります。

next.config.js
module.exports = {
  skipMiddlewareUrlNormalize: true,
}
middleware.js
export default async function middleware(req) {
  const { pathname } = req.nextUrl

  // GET /_next/data/build-id/hello.json

  console.log(pathname)
  // フラグがある場合、これは/_next/data/build-id/hello.jsonになります
  // フラグがない場合、これは/helloに正規化されます
}

ランタイム​

Middlewareは現在、Edge runtimeと互換性のあるAPIのみをサポートしています。Node.jsにのみ専用のAPIはサポートされていません。

バージョン履歴​

バージョン変更
v13.1.0高度なミドルウェアフラグが追加されました
v13.0.0ミドルウェアはリクエストヘッダー、レスポンスヘッダーを変更し、レスポンスを送信できます
v12.2.0ミドルウェアは安定版になりました。アップグレードガイドを参照してください
v12.0.9Edge Runtimeで絶対URLを強制PR
v12.0.0ベータ版のミドルウェアが追加されました