[Next.js Middleware 완전 정복] 로그인 인증, 리디렉션, 권한 제어까지 실무 예제로!

1. middleware란?

라우트 요청이 들어오기 전에 실행되는 서버 측 코드

 

Next.js의 middleware는 사용자의 요청이 서버에 도달하기 전에
리디렉션, 쿠키 검사, 헤더 추가, 인증 확인 등의 작업을 처리할 수 있는 기능입니다.

 

• 요청(Request)과 응답(Response) 사이에서 동작
• 쿠키/헤더 검사 가능
• next/server의 NextResponse 사용
• 모든 라우트에 대한 접근 제어 가능

 

2. 기본 구조

2-1. 파일 위치 및 구조

project-root/
├── app/
│   └── layout.tsx
├── middleware.ts  ← 루트에 위치

 

 

/login을 제외한 모든 페이지 접근 시, 토큰 없으면 로그인 페이지로 리디렉션

// middleware.ts (루트에 위치)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('accessToken');

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

 

3. matcher 설정(적용 범위 제한)

middleware.ts 파일과 함께 export const config를 사용해 어떤 경로에 middleware를 적용할지 지정할 수 있음

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

✅ /dashboard, /mypage 하위 URL에만 middleware 실행됨
✅ 정규표현식처럼 :path*로 하위 경로 전부 매칭 가능

 

 

4. 실무에서 자주 쓰는 예시

4-1. 로그인 인증 처리

if (!request.cookies.get('accessToken')) {
  return NextResponse.redirect(new URL('/login', request.url));
}

 

4-2. 로그인한 사용자는 /login 접근 못하게

if (request.nextUrl.pathname.startsWith('/login') && token) {
  return NextResponse.redirect(new URL('/dashboard', request.url));
}

 

4-3. locale에 따라 리디렉션

const locale = request.headers.get('accept-language')?.includes('ko')
  ? 'ko'
  : 'en';
return NextResponse.redirect(new URL(`/${locale}`, request.url));