Middleware

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

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

ユースケース

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

認証と認可：特定のページやAPIルートへのアクセスを許可する前に、ユーザーの身元を確認し、セッションcookieをチェックします
サーバーサイドリダイレクト：特定の条件（例：ロケール、ユーザーロール）に基づいてサーバーレベルでユーザーをリダイレクトします
パスのリライト：リクエストのプロパティに基づいて、APIルートやページへのパスを動的にリライトすることで、A/Bテスト、機能の展開、またはレガシーパスをサポートします
ボット検出：ボットトラフィックを検出してブロックすることで、リソースを保護します
ロギングと分析：ページや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に集約して集中管理できます。単一のミドルウェアファイルを強制することで、設定が簡素化され、潜在的な競合が防止され、複数のミドルウェア層を回避することでパフォーマンスが最適化されます。

例

TypeScript
JavaScript

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))
}

// 詳細は以下の「パスの一致」を参照してください
export const config = {
  matcher: '/about/:path*',
}

middleware.js
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はプロジェクト内のすべてのルートに対して呼び出されます。したがって、特定のルートを正確にターゲットまたは除外するためにマッチャーを使用することが重要です。実行順序は次のとおりです：

next.config.jsのheaders
next.config.jsのredirects
Middleware（rewrites、redirectsなど）
next.config.jsのbeforeFiles（rewrites）
ファイルシステムルート（public/、_next/static/、pages/、app/など）
next.config.jsのafterFiles（rewrites）
Dynamic Routes（/blog/[slug]）
next.config.jsのfallback（rewrites）

Middlewareが実行されるパスを定義する方法は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の値はビルド時に静的に解析できるように定数である必要があります。変数などの動的な値は無視されます。

設定されたマッチャー：

/で始まる必要があります
名前付きパラメーターを含めることができます：/about/:pathは/about/aと/about/bにマッチしますが、/about/a/cにはマッチしません
名前付きパラメーターに修飾子を付けることができます（:で始まる）：/about/:path*は/about/a/b/cにマッチします。*はゼロまたはそれ以上、?はゼロまたは1、+は1以上です
括弧で囲まれた正規表現を使用できます：/about/(.*)は/about/:path*と同じです

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

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

条件文

TypeScript
JavaScript

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))
  }
}

middleware.js
import { NextResponse } from 'next/server'

export function middleware(request) {
  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 Routes、getServerSideProps、およびrewriteの宛先に対してリクエストヘッダーを設定する
レスポンスcookieを設定する
レスポンスヘッダーを設定する

Middlewareからレスポンスを生成するには、次の方法があります：

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

Cookieの使用

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

受信リクエストの場合、cookiesには次のメソッドがあります：get、getAll、set、およびdelete cookies。hasを使用してcookieの存在を確認したり、clearですべてのcookieを削除したりできます。
送信レスポンスの場合、cookiesには次のメソッドがあります：get、getAll、set、およびdelete。

TypeScript
JavaScript

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
}

middleware.js
import { NextResponse } from 'next/server'

export function middleware(request) {
  // 受信リクエストに"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=/test`ヘッダーが含まれます。

  return response
}

ヘッダーの設定

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

TypeScript
JavaScript

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
}

middleware.js
import { NextResponse } from 'next/server'

export function middleware(request) {
  // リクエストヘッダーをクローンし、新しいヘッダー`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ヘッダーを設定して、シンプルおよびプリフライトリクエストを含むクロスオリジンリクエストを許可できます。

TypeScript
JavaScript

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

middleware.js
import { 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) {
  // リクエストからオリジンを確認します
  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以降で利用可能です）。

TypeScript
JavaScript

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 }
    )
  }
}

middleware.js
import { isAuthenticated } from '@lib/auth'

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

export function middleware(request) {
  // リクエストを確認するために認証関数を呼び出します
  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()
}

高度なMiddlewareフラグ

Next.jsのv13.1では、skipMiddlewareUrlNormalizeとskipTrailingSlashRedirectという2つの追加フラグがMiddlewareに導入され、高度なユースケースに対応しています。

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に正規化されます
}

ユニットテスト（実験的）

Next.js 15.1から、next/experimental/testing/serverパッケージには、ミドルウェアファイルをユニットテストするためのユーティリティが含まれています。ミドルウェアのユニットテストは、コードが本番環境に到達する前に、ミドルウェアが意図したパスでのみ実行され、カスタムルーティングロジックが正しく機能することを確認するのに役立ちます。

unstable_doesMiddlewareMatch関数を使用して、提供されたURL、ヘッダー、およびcookieに対してミドルウェアが実行されるかどうかを確認できます。

import { unstable_doesMiddlewareMatch } from 'next/experimental/testing/server'

expect(
  unstable_doesMiddlewareMatch({
    config,
    nextConfig,
    url: '/test',
  })
).toEqual(false)

ミドルウェア関数全体もテストできます。

import { isRewrite, getRewrittenUrl } from 'next/experimental/testing/server'

const request = new NextRequest('https://nextjs.org/docs')
const response = await middleware(request)
expect(isRewrite(response)).toEqual(true)
expect(getRewrittenUrl(response)).toEqual('https://other-domain.com/docs')
// レスポンスがリダイレクトであれば、getRedirectUrlも使用できます

ランタイム

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

バージョン履歴

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

ユースケース​

規約​

例​

パスの一致​

マッチャー​

条件文​

NextResponse​

Cookieの使用​

ヘッダーの設定​

CORS​

レスポンスの生成​

waitUntilとNextFetchEvent​

高度なMiddlewareフラグ​

ユニットテスト（実験的）​

ランタイム​

バージョン履歴​