Next.js Middleware

Next.js Middleware 

Next.js의 Middleware는 요청(Request)과 응답(Response) 사이에서 실행되는 코드로, 특정 경로로 요청이 들어올 때 실행되어 응답을 변경하거나 요청을 제어할 수 있습니다.

Middleware를 활용하면 사용자 인증, 요청 리디렉션, A/B 테스트, 국제화(i18n) 처리 등 다양한 기능을 구현할 수 있습니다.

 

Middleware

Middleware의 주요 특징

• 요청을 가로채서 특정 로직을 실행할 수 있음
• Next.js의 Edge Runtime에서 실행되어 빠름
• 서버리스 환경에서 동작
• API Route 및 특정 페이지 보호 가능

middleware.ts 또는 middleware.js 파일을 생성하여 구현할 수 있습니다.

 

---

 

Middleware

middleware.ts 파일을 생성하고, NextRequest와 NextResponse를 사용하여 요청을 조작할 수 있습니다.

import { NextRequest, NextResponse } from 'next/server';

export function middleware(req: NextRequest) {
  // 요청 URL 확인
  const { pathname } = req.nextUrl;

  // 특정 경로에서 리디렉션
  if (pathname === '/old-route') {
    return NextResponse.redirect(new URL('/new-route', req.url));
  }

  // 특정 헤더 추가
  const response = NextResponse.next();
  response.headers.set('X-Custom-Header', 'MyMiddleware');
  return response;
}

 

---

 

특정 경로에서 Middleware 실행하기

Next.js는 config.matcher 옵션을 제공하여 특정 경로에서만 Middleware를 실행할 수 있습니다.

export const config = {
  matcher: ['/dashboard/:path*', '/profile'],
};

• 위 설정은 /dashboard/ 하위 모든 경로와 /profile 페이지에서만 Middleware가 실행됩니다.

 

---

 

Middleware 활용 예제

사용자 인증 (JWT 기반 보호)

로그인이 필요한 페이지에 접근할 때, 인증이 되어 있지 않으면 로그인 페이지로 리디렉션합니다.

import { NextRequest, NextResponse } from 'next/server';

export function middleware(req: NextRequest) {
  const token = req.cookies.get('token')?.value;
  const loginUrl = new URL('/login', req.url);

  if (!token) {
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/settings'],
};

 

 

A/B 테스트 적용

사용자를 랜덤하게 A/B 그룹으로 나누어 다른 페이지를 보여주는 방식입니다.

import { NextRequest, NextResponse } from 'next/server';

export function middleware(req: NextRequest) {
  const variant = Math.random() < 0.5 ? 'A' : 'B';
  const url = new URL(req.url);

  if (variant === 'A') {
    url.pathname = '/experiment-A';
  } else {
    url.pathname = '/experiment-B';
  }

  return NextResponse.rewrite(url);
}

export const config = {
  matcher: ['/experiment'],
};

 

 

국제화(i18n) 자동 라우팅

사용자의 요청 헤더에서 언어를 감지하고 해당 언어의 페이지로 이동시킵니다.

import { NextRequest, NextResponse } from 'next/server';

export function middleware(req: NextRequest) {
  const acceptLanguage = req.headers.get('accept-language');
  let locale = 'en';

  if (acceptLanguage?.startsWith('ko')) {
    locale = 'ko';
  } else if (acceptLanguage?.startsWith('fr')) {
    locale = 'fr';
  }

  const url = new URL(`/${locale}${req.nextUrl.pathname}`, req.url);
  return NextResponse.redirect(url);
}

export const config = {
  matcher: ['/'],
};

 

---

Middleware의 동작 방식

Middleware는 Edge Runtime에서 실행되며, API Route, getServerSideProps, app/api 내부 코드보다 먼저 실행됩니다.

요청(Request) → Middleware 실행 → 응답(Response) 처리 또는 리다이렉트

Middleware는 아래 네 가지 방식으로 응답을 처리할 수 있습니다.

NextResponse.next()	요청을 계속 진행시킴
NextResponse.redirect(url)	특정 URL로 이동
NextResponse.rewrite(url)	요청을 다른 페이지로 변경
NextResponse.json(data, options?)	JSON 응답 반환

 

---

Middleware의 단점

• 서버에서만 실행되며, 클라이언트 측 코드에서는 사용할 수 없음
• Edge Functions에서 실행되므로 일부 Node.js 기능(fs 모듈 등)은 사용할 수 없음
• API Route와 달리 요청 본문(req.body)을 읽을 수 없음