[Next.js] Middleware(미들웨어)

 

🚀 [Next.js] Middleware(미들웨어)

모든 프로젝트는 Windows 환경에서 진행됩니다.

목차

• Next 프로젝트에서 미들웨어란?
• middleware.ts 파일 위치
  • 파일 구조 예시
  • 주의사항
  • 미들웨어 적용 경로 설정(matcher)
• middleware.ts의 역할
• middleware.ts 예시
  • 예시 코드 설명
• middleware 사용법
• 정리

---

Next 프로젝트에서 미들웨어란?

미들웨어(middleware)는 Next.js에서 요청(request)과 응답(response) 사이에 실행되는 중간 처리 로직을 담당하는 파일입니다.

이 파일은 사용자가 페이지에 접근하기 전에 필요한 작업을 수행할 수 있는 중요한 역할을 합니다.

---

middleware.ts 파일 위치

Next 프로젝트에서 미들웨어는 Next.js 프로젝트의 최상위(root) 디렉토리에 위치해야합니다.

Next.js는 이 파일을 자동으로 인식하여 전역 미들웨어로 적용하므로, 정확한 위치에 두는 것이 중요합니다.

 

파일 구조 예시

/my-next-app
  ├── public/           # 정적 파일 (이미지, 폰트 등)
  ├── src/              # 소스 코드 폴더
  ├── pages/            # 페이지 라우트
  ├── app/              # App Router 사용 시 페이지 정의
  ├── middleware.ts     # 미들웨어 파일 (루트에 위치)
  ├── next.config.js    # Next.js 설정 파일
  ├── package.json      # 프로젝트 정보 및 의존성
  └── node_modules/     # 설치된 패키지들

 

주의사항

• 프로젝트의 최상위 루트에 있어야 합니다. (src/ 폴더 안이 아닌, 루트 디렉터리)
• 이름은 반드시 middleware.ts 또는 middleware.js여야 하며, 다른 이름으로 변경할 수 없습니다.
• App Router와 Pages Router 모두 동작합니다.

 

미들웨어 적용 경로 설정 (matcher)

모든 요청에 대해 실행될 필요가 없다면, matcher 옵션을 사용해 특정 경로에만 적용되도록 설정할 수 있습니다.

// middleware.ts

export const config = {
  matcher: ['/dashboard/:path*', '/profile/:path*'], // 특정 경로에만 미들웨어 적용
};

---

middleware.ts의 역할

middleware.ts는 다음과 같은 역할을 합니다.

• 인증 처리 (Authentication):
  로그인된 사용자인지 확인하고, 로그인되지 않았다면 로그인 페이지로 리디렉션합니다.
• 권한 확인 (Authorization):
  특정 페이지는 관리자만 접근할 수 있도록 제한할 수 있습니다.
• 리다이렉트 (Redirect):
  사용자가 특정 페이지에 접근하려 할 때 다른 페이지로 이동시킵니다.
• 언어 설정 (Localization):
  사용자의 브라우저 언어를 감지해 해당 언어의 페이지로 리디렉션합니다.

---

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('authToken'); // 쿠키에서 토큰 확인

  if (!token) {
    // 토큰이 없으면 로그인 페이지로 리디렉션
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // 토큰이 있으면 요청을 그대로 진행
  return NextResponse.next();
}

// 어떤 경로에 대해 미들웨어가 적용될지 설정 (optional)
export const config = {
  matcher: ['/dashboard/:path*'], // 특정 경로에만 미들웨어 적용
};

 

예시 코드 설명

1. NextResponse와 NextRequest:
   • NextRequest: 들어온 요청을 다루는 객체입니다. (ex. 쿠키, 헤더 등 확인)
   • NextResponse: 응답을 생성하고, 페이지를 리디렉션하거나 상태 코드를 반환합니다.
2. middleware() 함수:
   • 사용자가 대시보드(/dashboard) 페이지에 접근할 때 이 미들웨어가 실행됩니다.
   • 쿠키에 authToken이 없으면 /login 페이지로 리디렉션합니다.
3. matcher 설정:
   • 이 옵션을 사용해 특정 경로에만 미들웨어가 적용되도록 할 수 있습니다.
   • 예: /dashboard와 그 하위 경로들에만 미들웨어가 적용됩니다.

---

middleware 사용법

언제 middleware를 사용하면 좋을까?

• 로그인 여부나 사용자 권한에 따라 특정 페이지 접근을 제한하고 싶을 때
• 모든 요청에 대해 공통적으로 처리해야 할 로직이 있을 때 (예: 로깅, 언어 설정)
• 사용자를 특정 페이지로 리디렉션해야 할 때

---

📋 정리

middleware.ts는 Next.js 애플리케이션에서 요청과 응답 사이에 실행되는 중요한 중간 처리기입니다.

인증과 권한 관리뿐만 아니라 다양한 요청을 필터링하거나 리디렉션할 수 있어, 웹 애플리케이션의 보안과 사용자 경험을 향상시키는 데 유용합니다.

미들웨어를 적절히 활용해 프로젝트를 더 스마트하게 관리해보세요! ✨🛰️