Next.js에서 middleware 사용하기

미들웨어란?

미들웨어는 요청이 완료되기 전에 실행되는 코드입니다. 그런 다음 요청 또는 응답 헤더를 수정하거나 리디렉션할 수 있습니다. Next.js에서는 페이지나 API 라우트가 실행되기 전에 미들웨어를 통해 요청을 가로채고 수정할 수 있습니다.

주요특징

Edge Runtime에서 실행 (Node.js Runtime으로 변경가능)
페이지 렌더링 전에 동작
요청/응답 수정 가능
조건부 라우팅

기본 설정

파일 위치

미들웨어 파일은 프로젝트 루트 또는 src 폴더에 위치해야 합니다

your-project/
├── middleware.ts    # 루트에 위치
└── src/
    └── middleware.ts # 또는 src 폴더에 위치

기본 구조

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

export async function middleware(request: NextRequest) {
  return NextResponse.next()
}

경로 매칭 설정

export const config = {
  matcher: [
    '/api/:path*', // API 경로
    '/dashboard/:path*', // 대시보드 경로
    '/((?!public|static|api).*)', // 제외 경로 패턴
  ],
}

이렇게 matcher 를 통해 미들웨어가 실행될 경로를 제어할 수 있습니다.

미들웨어는 프로젝트의 모든 경로에 대해 호출되며, matcher를 사용하여 특정 경로를 정확하게 지정하거나 제외하는 것이 중요합니다.
matcher 값은 상수여야 빌드 타임에 정적으로 분석할 수 있습니다.
matcher 배열의 순서대로 패턴 매칭을 검사합니다.

사용예제

1. 인증 처리

// 토큰이 없이 로그인 페이지로 리다이렉트되며, 로그인 성공시 다시 돌아옵니다.
export async function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token')

  if (!token) {
    const from = encodeURIComponent(request.nextUrl.pathname)
    return NextResponse.redirect(new URL(`/login?from=${from}`, request.url))
  }

  return NextResponse.next()
}

// 미들웨어는 dashboard로 시작하는 경로에만 적용!
export const config = {
  matcher: '/dashboard/:path*',
}

2. 국제화 처리 (i18n)

export function middleware(request: NextRequest) {
  // 사용자 언어 감지
  const acceptLanguage = request.headers.get('accept-language')?.split(',')[0] || 'ko'

  // 현재 경로에 언어 코드가 없는 경우
  if (!request.nextUrl.pathname.startsWith('/ko') && !request.nextUrl.pathname.startsWith('/en')) {
    return NextResponse.redirect(
      new URL(`/${acceptLanguage}${request.nextUrl.pathname}`, request.url)
    )
  }
}

3. 응답 헤더 설정

export function middleware(request: NextRequest) {
  const response = NextResponse.next()

  // CORS 헤더 설정
  response.headers.set('Access-Control-Allow-Origin', '*')
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE')

  // 보안 헤더 설정
  response.headers.set('X-Frame-Options', 'DENY')
  response.headers.set('X-Content-Type-Options', 'nosniff')

  return response
}

위 예제 외에도 미들웨어를 사용하여 로깅 시스템 구축, API 요청 제한, 지역 기반 리다이렉션, 캐시 제어등에 사용할 수 있습니다. 더 많은 예제는 next.js 레포지토리에서 확인할 수 있습니다.

next.js 레포지토리
next.js 공식문서