ミドルウェア

ミドルウェアを使用すると、リクエストが完了する前にコードを実行できます。そして、受信したリクエストに基づいて、レスポンスを書き換えたり、リダイレクトしたり、リクエストやレスポンスのヘッダーを変更したり、直接レスポンスを返したりできます。

ミドルウェアはキャッシュされたコンテンツやルートがマッチングされる前に実行されます。詳細はパスマッチングを参照してください。

ユースケース

ミドルウェアが効果的な一般的なシナリオ:

受信リクエストの一部を読み取った後のクイックリダイレクト
A/Bテストや実験に基づいて異なるページに書き換え
すべてのページまたは一部のページのヘッダーを変更

ミドルウェアが適さないケース:

遅いデータフェッチ
セッション管理

規約

プロジェクトのルートにmiddleware.ts（または.js）ファイルを使用してミドルウェアを定義します。例えば、pagesやappと同じレベル、またはsrc内（該当する場合）。

注: プロジェクトごとに1つのmiddleware.tsファイルしかサポートされていませんが、ミドルウェアロジックをモジュール化して整理することは可能です。ミドルウェア機能を個別の.tsまたは.jsファイルに分割し、メインの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))
}

// 詳細は「パスマッチング」を参照
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*',
}

パスマッチング

ミドルウェアはプロジェクト内のすべてのルートに対して呼び出されます。このため、特定のルートを正確にターゲットまたは除外するためにマッチャーを使用することが重要です。実行順序は次のとおりです:

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を使用すると、特定のパスでミドルウェアを実行するようにフィルタリングできます。

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.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' }],
    },
  ],
}

知っておくと良い: 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のマッチャーはマッチします。

条件文

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

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ルート、getServerSideProps、rewrite先のリクエストヘッダーを設定する
レスポンスのクッキーを設定する
レスポンスヘッダーを設定する

ミドルウェアからレスポンスを生成するには、次のいずれかを行います:

レスポンスを生成するルート（PageまたはRoute Handler）にrewriteする
NextResponseを直接返す。レスポンスの生成を参照

クッキーの使用

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

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

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // 受信リクエストに「Cookie:nextjs=fast」ヘッダーがあると仮定
  // `RequestCookies` APIを使用してリクエストからクッキーを取得
  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を使用してレスポンスにクッキーを設定
  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
}

import { NextResponse } from 'next/server'

export function middleware(request) {
  // 受信リクエストに「Cookie:nextjs=fast」ヘッダーがあると仮定
  // `RequestCookies` APIを使用してリクエストからクッキーを取得
  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を使用してレスポンスにクッキーを設定
  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以降で利用可能）。

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
}

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
}

知っておくと良い: バックエンドのWebサーバー設定によっては、大きなヘッダーを設定すると431 Request Header Fields Too Largeエラーが発生する可能性があるため、避けてください。

CORS

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

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

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

知っておくと良い: Route Handlersで個々のルートのCORSヘッダーを設定できます。

レスポンスの生成

ミドルウェアから直接、Response または NextResponse インスタンスを返すことでレスポンスを生成できます。（これは Next.js v13.1.0 以降で利用可能）

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

// ミドルウェアを `/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 }
    )
  }
}

import { isAuthenticated } from '@lib/auth'

// ミドルウェアを `/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() メソッドはプロミスを引数に取り、そのプロミスが解決するまでミドルウェアのライフタイムを延長します。これはバックグラウンドで作業を実行するのに便利です。

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 の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 になる
}

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

Next.js 15.1以降、next/experimental/testing/server パッケージにはミドルウェアファイルのユニットテストを支援するユーティリティが含まれています。ミドルウェアのユニットテストを行うことで、コードが本番環境に到達する前に、目的のパスでのみ実行されることや、カスタムルーティングロジックが意図した通りに動作することを確認できます。

unstable_doesMiddlewareMatch 関数を使用して、提供されたURL、ヘッダー、クッキーに対してミドルウェアが実行されるかどうかをアサートできます。

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も使用可能

ランタイム

ミドルウェアはデフォルトでEdgeランタイムを使用します。v15.2（canary）以降、Node.jsランタイムを使用する実験的サポートが追加されました。有効にするには、next.config ファイルにフラグを追加します：

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    nodeMiddleware: true,
  },
}

export default nextConfig

const nextConfig = {
  experimental: {
    nodeMiddleware: true,
  },
}

export default nextConfig

そして、ミドルウェアファイルで config オブジェクト内のランタイムを nodejs に設定します：

export const config = {
  runtime: 'nodejs',
}

export const config = {
  runtime: '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`	ミドルウェア（ベータ）が追加

On this page