ミドルウェア

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

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

規約

プロジェクトのルートにmiddleware.ts（または.js）ファイルを配置してミドルウェアを定義します。例えば、pagesやappと同じ階層、またはsrcディレクトリ内（使用可能な場合）に配置します。

例

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設定
条件文

Matcher

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（ファビコンファイル）
     */
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
}

豆知識：matcherの値はビルド時に静的に解析できるように定数である必要があります。変数などの動的な値は無視されます。

設定された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のmatcherはマッチします。

条件文

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または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メソッドがあります。

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=/test`ヘッダーが含まれます

  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.rewriteでもリクエストヘッダーを設定できます
  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.rewriteでもリクエストヘッダーを設定できます
  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エラーが発生する可能性があるため、大きなヘッダーを設定しないでください。

レスポンスの生成

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

import { 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: '認証に失敗しました' },
      { 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: '認証に失敗しました' },
      { status: 401 }
    )
  }
}

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

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

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+)/)
  ) {
    req.nextUrl.pathname += '/'
    return NextResponse.redirect(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 に正規化される
}

バージョン履歴

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

On this page