Next.js 교재 · 13편 · Middleware

Middleware — 요청 가로채기·리디렉트·인증

모든 요청이 페이지에 닿기 전 한 번 거쳐가는 관문. 인증·국가별 리디렉트·로깅.

"로그인 안 한 사용자가 /dashboard 들어오면 /login 으로 보내라" 같은 일을 페이지마다 적으면 곧 지옥이다. 50 페이지에 같은 인증 체크 코드 50번.

Next.js 의 답이 Middleware. 프로젝트 루트에 middleware.ts 한 파일 — 모든 요청이 페이지·API 핸들러에 도달하기 전에 거쳐간다. 인증·리디렉트·헤더 조작·로깅을 한 곳에서.

1. 가장 단순한 Middleware

middleware.ts 를 프로젝트 루트에 둔다 (app/ 안 아님!).

// middleware.ts (프로젝트 루트)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(req: NextRequest) {
  console.log(`[mw] ${req.method} ${req.nextUrl.pathname}`);
  return NextResponse.next();   // 통과 — 페이지로 진행
}

이 한 파일로 모든 요청이 콘솔에 기록된다. NextResponse.next() 가 "통과" 신호. 다른 반환값은 흐름을 바꾼다.

2. 리디렉트 — 조건부 분기

로그인 안 된 사용자를 차단하는 가장 흔한 패턴.

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';

export function middleware(req: NextRequest) {
  const token = req.cookies.get('session')?.value;
  const isProtected = req.nextUrl.pathname.startsWith('/dashboard');

  if (isProtected && !token) {
    const url = req.nextUrl.clone();
    url.pathname = '/login';
    url.searchParams.set('returnTo', req.nextUrl.pathname);
    return NextResponse.redirect(url);
  }

  return NextResponse.next();
}

req.cookies.get 로 세션 쿠키 확인, 없으면 NextResponse.redirect. URL 객체는 req.nextUrl.clone() 로 복제해 안전하게 수정. returnTo 쿼리로 원래 가려던 경로 기억.

3. matcher — 어느 경로에만 적용할지

위 미들웨어는 모든 요청에 실행돼 정적 파일·이미지까지 거친다. 비효율. matcher 로 특정 경로만 타게 한다.

// middleware.ts (이어서)
export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/admin/:path*',
    /*
     * 모든 경로 매칭, 단 아래는 제외:
     * - _next/static (정적 파일)
     * - _next/image (이미지 최적화)
     * - favicon.ico · public 폴더
     */
    {
      source: '/((?!_next/static|_next/image|favicon.ico|public).*)',
    },
  ],
};

두 가지 형태 — 단순 패턴(/dashboard/:path*) 또는 객체 형태(부정 lookahead 정규식). 정규식이 강력하지만 가독성 떨어지니, 보호 경로만 명시적으로 나열하는 게 유지보수에 좋다.

matcher 구문 — :path* (0개 이상 세그먼트), :slug (정확히 한 세그먼트). path-to-regexp 기반이라 Express 와 같은 문법. 정확히 알고 싶으면 path-to-regexp 문서가 참고.

4. 헤더와 쿠키 조작

응답 헤더 추가·쿠키 설정도 미들웨어에서.

export function middleware(req: NextRequest) {
  const res = NextResponse.next();

  // 응답 헤더 추가
  res.headers.set('X-Country', req.geo?.country ?? 'KR');
  res.headers.set('X-Request-Id', crypto.randomUUID());

  // 쿠키 설정
  res.cookies.set('lastVisit', new Date().toISOString(), {
    maxAge: 60 * 60 * 24 * 30,
    httpOnly: true,
    secure: true,
  });

  return res;
}

특히 req.geo(Vercel 환경에서 IP 기반 국가·도시 자동 감지) 와 결합한 지역별 리디렉트가 인기 패턴 — /ko·/en 자동 분기, 한국 트래픽만 다른 결제 페이지 등.

5. Edge Runtime 의 제약

Middleware 는 기본적으로 Edge Runtime 에서 실행. Node 가 아니라 V8 isolates 환경.

못 쓰는 것들 — Node API (fs·net·http·crypto 대부분) 사용 불가. npm 패키지 중 Node 의존 큰 것들은 안 돌아간다. 가능한 것 — fetch, Web Crypto, URL, Headers, Request, Response, cookies. JWT 검증은 jose 같은 Edge 호환 라이브러리로.

Edge Runtime 의 이유는 속도. 사용자와 가까운 CDN 엣지에서 실행돼 50ms 이내 응답. 인증 가드·국가 라우팅 같은 빠르게 끝나야 하는 일에 최적. 무거운 DB 호출이 필요하면 미들웨어 안에서 하지 말고 페이지에서 Server Component 로.

꼭 Node 가 필요하면 Next 15.2 부터 export const runtime = 'nodejs' 지정 가능. 단 엣지 속도는 포기.

흔한 패턴 4가지

패턴	구현
인증 가드	쿠키 확인 → `NextResponse.redirect('/login')`
A/B 테스트	쿠키로 variant 결정 → `NextResponse.rewrite`
지역별 리디렉트	`req.geo.country` 기반 분기
봇 차단	`user-agent` 검사 → 403 응답

rewrite vs redirect — redirect 는 URL 바꿔서 클라이언트가 다시 요청, rewrite 는 URL 은 그대로 유지하면서 내부적으로 다른 페이지 렌더. A/B 테스트는 rewrite 가 적합 (사용자는 URL 변화 모름).

요약 — 13편 좌표

여기까지 정리. middleware.ts 한 파일이 모든 요청의 관문. NextResponse.next/redirect/rewrite/json 으로 흐름 결정. matcher 로 적용 경로 좁히기 (성능 + 명확성). 헤더·쿠키 조작은 응답 객체에 직접. Edge Runtime 제약 (Node API 못 씀) 은 빠른 응답을 위한 트레이드오프. 인증 가드·A/B·지역 라우팅이 주된 사용처. 다음 편에서 Route Handlers 로 API 엔드포인트를 만든다.

다음 편 예고 — Route Handlers (API)

app/api 폴더로 만드는 RESTful 엔드포인트. 14편.