Next.js middleware는 무엇에 사용하나요?

Question

Accepted Answer

**middleware**는 **요청이 완료되기 전에** 실행되는 코드입니다. 페이지나 라우트 핸들러가 렌더링되기 전, Edge에서 실행됩니다. 요청을 검사하고 rewrite/redirect하거나, 헤더를 설정하거나, 여러 라우트에 대한 인증을 한곳에서 확인할 수 있게 해 줍니다.

## middleware 정의

```ts
// middleware.ts (프로젝트 루트에)
import { NextRequest, NextResponse } from "next/server";

export function middleware(req: NextRequest) {
  const token = req.cookies.get("session")?.value;

// /dashboard 보호 — 인증되지 않은 사용자를 로그인으로 리다이렉트
  if (req.nextUrl.pathname.startsWith("/dashboard") && !token) {
    return NextResponse.redirect(new URL("/login", req.url));
  }
  return NextResponse.next(); // 요청 진행 허용
}

// 이 경로들에서만 실행 (성능 — 모든 자산에서 실행되지 않도록)
export const config = { matcher: ["/dashboard/:path*", "/account/:path*"] };
```

## middleware가 할 수 있는 것

```ts
NextResponse.redirect(url);          // 사용자를 다른 곳으로 보냄 (인증 게이트)
NextResponse.rewrite(url);           // URL은 그대로, 다른 콘텐츠 제공 (A/B, i18n)
NextResponse.next();                  // 진행, 선택적으로 헤더 수정
// req.geo / req.cookies / req.headers — 위치, 인증 등 검사
```

흔한 용도: **인증 게이팅**, **리다이렉트**(로케일/지역 기반, www→apex), rewrite를 통한 **A/B 테스트**, **보안 헤더** 설정, 봇/기능 플래그.

## 핵심 제약

```text
⚠️ Edge 런타임에서 실행 → Node.js API 없음 (no fs, 제한된 라이브러리)
⚠️ 빨라야 함 — 매칭된 모든 요청 전에 실행됨; 무거운 작업은 지연을 더함
⚠️ 복잡한 인증을 위해 데이터베이스에 직접 접근 불가 — 가벼운 검사만 (예: JWT/쿠키 존재 확인);
   전체 인증은 페이지/핸들러에서
```

`matcher` 설정이 중요합니다. middleware를 필요한 라우트로만 제한하여 정적 자산에서 실행되어 전체를 느리게 만들지 않도록 하세요.

## 왜 중요한가

middleware는 횡단 관심사 요청 로직 — 인증 리다이렉트, 로케일 routing, rewrite, 헤더 — 을 위한 단일 병목 지점입니다. 각 페이지에 코드를 반복하지 않고 여러 라우트에 적용됩니다.

Edge 제약(빠름, Node API 없음, 가벼운 검사만)과 `matcher` 스코핑을 아는 것이 게이트키핑과 routing 관심사에 이를 올바르게 사용하는 비결입니다.