Next.js App Router를 사용하다 보면
사용자가 페이지에 진입하기 전에 공통 로직을 처리해야 하는 경우가 자주 발생한다.
예를 들어:
- 로그인 여부 확인 (인증)
- 특정 페이지 접근 제한
- 요청 로깅
- 조건에 따른 리다이렉트
이런 로직을 페이지나 API마다 반복 구현하면 코드가 분산되고 관리가 어려워진다.
이때 사용하는 기능이 Middleware이다.
1. Middleware란?
Middleware는 요청이 라우트에 도달하기 전에 실행되는 함수이다.
👉 요청을 가로채서 사전에 처리할 수 있다.
실행 흐름
Request → Middleware → Route → Response역할
- 인증 처리
- 리다이렉트
- 요청 검사
- 로깅
2. 기본 구조
Middleware는 프로젝트 루트에 middleware.ts로 작성한다.
예시
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
return NextResponse.next();
}핵심 포인트
- 모든 요청 전에 실행됨
NextRequest,NextResponse사용next()호출 시 다음 단계로 전달
3. 실행 범위 (matcher)
기본적으로 모든 요청에 실행되므로
필요한 경로에만 적용하는 것이 중요하다.
예시
export const config = {
matcher: ['/dashboard/:path*'],
};👉 /dashboard 이하 경로에만 적용
4. 인증 처리 (Auth)
가장 많이 사용하는 패턴
예시
export function middleware(request: NextRequest) {
const token = request.cookies.get('token');
if (!token) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}포인트
- 쿠키 / 헤더 기반 인증
- 접근 제어 로직 중앙 관리
5. redirect vs rewrite
redirect
- URL 변경됨
return NextResponse.redirect(new URL('/login', request.url));rewrite
- URL 유지, 내부 라우팅 변경
return NextResponse.rewrite(new URL('/home', request.url));👉 redirect = 이동 / rewrite = 내부 매핑
6. 요청 가공 및 공통 처리
전역적으로 적용되는 공통 로직 처리 가능
예시
export function middleware(request: NextRequest) {
const response = NextResponse.next();
response.headers.set('x-custom-header', 'middleware');
return response;
}활용
- 공통 헤더
- 보안 설정
- 요청 추적
- A/B 테스트
7. Edge Runtime
Middleware는 Edge Runtime에서 실행된다.
👉 Edge Runtime = 사용자와 가까운 서버(CDN 위치)에서 코드를 실행하는 환경
특징
- 빠른 응답
- 사용자와 가까운 위치에서 실행
- 요청 초기에 처리
주의사항
- Node.js API 사용 불가
- DB 직접 접근 비추천
- 무거운 로직 부적합
👉 가벼운 분기 처리에 적합
8. 실행 순서
Next.js의 요청 처리 흐름은 다음과 같다.
Middleware → Route Handler / Page → Response👉 Middleware는 항상 가장 먼저 실행된다.
즉, 실제 페이지나 API 로직이 실행되기 전에 요청을 선별하고 제어하는 역할을 담당한다.
9. 언제 사용해야 할까?
다음과 같은 "요청 이전 단계에서 처리해야 하는 로직"에 적합하다.
인증 / 권한 처리
- 로그인 여부 확인
- 관리자 페이지 접근 제한
리다이렉트
- 로그인 상태에 따른 페이지 이동
- 특정 조건에 따른 경로 변경
공통 로직 처리
- 요청 로깅
- A/B 테스트
- 트래픽 제어
👉 공통적으로 여러 페이지에서 반복되는 로직일수록 Middleware에 적합하다.
10. 사용하면 안 되는 경우
Middleware는 모든 요청마다 실행되기 때문에
👉 무거운 로직을 처리하기에는 적합하지 않다.
피해야 할 경우
- DB 접근
- 복잡한 비즈니스 로직
- 시간이 오래 걸리는 작업
👉 이런 로직은
Route Handler 또는 Server Action에서 처리하는 것이 적절하다.
11. 주의사항
정적 파일이나 내부 경로에도 Middleware가 실행될 수 있다.
예:
- /_next/*
- /favicon.ico
문제
불필요한 요청에도 Middleware가 실행되면서
👉 성능에 영향을 줄 수 있다.
해결
export const config = {
matcher: ['/((?!_next|favicon.ico).*)'],
};👉 필요한 경로에만 적용하도록 제한하는 것이 중요하다.
12. 핵심 정리
- 요청을 가로채는 사전 처리 레이어
- 인증, 리다이렉트, 로깅에 사용
- Edge Runtime에서 실행
- matcher로 범위 제어
- redirect / rewrite 구분 필요
한 줄 정리
Middleware는 요청 이전 단계에서 실행되어 인증, 리다이렉트 등 공통 로직을 처리하는 레이어이다.
마무리
Middleware는 요청이 실제 라우트에 도달하기 전에 실행되며,
Next.js의 서버 처리 흐름에서 가장 앞단에 위치한다.
Next.js에서는 서버 로직을 처리하는 방식이 나뉜다.
- 요청 이전 → Middleware
- API 처리 → Route Handlers
- UI 기반 변경 → Server Actions
👉 실행 위치를 기준으로 보면
각 기능의 역할과 사용 시점을 더 명확하게 구분할 수 있다.
