🛡️ Next.js 13장: Middleware & Edge Runtime — 요청을 가로채는 Edge 경비원

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 middleware.ts 기본 구조 — 모든 요청의 첫 관문 🟢
• 🔐 인증 리디렉트 패턴 — 로그인 안 한 사람 차단하기 🟡
• 🌍 Edge Runtime이란 무엇인가 🟡
• 🔒 보안 헤더 설정 — CSP와 HSTS 🔴
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분 (전체) / 핵심 파트만: 7분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(신입): "로그인 안 한 사용자가 /dashboard 페이지에 접근하려 하면 /login으로 보내야 하는데... 각 페이지 컴포넌트 상단마다 세션 체크 코드를 복붙해야 하나요? 페이지가 100개면 100군데 다 써야 해요?"
• 영호(리드): "절대 그러면 안 되죠! middleware.ts 파일 하나를 프로젝트 루트에 두면 돼요. 모든 요청이 페이지에 도착하기 전에 이 파일을 무조건 거치거든요. 경비원처럼 딱 한 곳에서 모든 출입을 통제하는 거예요."

🗺️ 이 문서의 흐름
Middleware 실행 위치 → 인증 리디렉트 → Edge Runtime 개념 → 보안 헤더 설정

🎯 이 문서를 다 읽으면 할 수 있는 것

• middleware.ts로 로그인 여부에 따라 페이지 접근을 제어할 수 있다
• matcher로 Middleware가 실행될 경로를 정밀하게 제어할 수 있다
• Edge Runtime이 Node.js와 어떻게 다른지 설명할 수 있다

🤔 왜 알아야 하는가

서비스를 만들다 보면 반드시 이런 요구사항이 생겨:

• 로그인한 사용자만 /dashboard, /my, /settings 접근 가능
• 특정 국가(지역)에 따라 다른 페이지로 라우팅 (A/B 테스트, 다국어)
• 모든 응답에 보안 헤더(X-Frame-Options, CSP) 자동 추가
• 특정 봇 또는 IP 차단

이걸 각 페이지마다 구현하면 코드 중복, 빠뜨리는 페이지 발생, 유지보수 난맥이 펼쳐져.

Middleware는 모든 요청의 공통 관문이야. CDN 엣지 노드에서 실행되기 때문에 서버나 DB에 도달하기도 전에, 심지어 Next.js 앱 자체에 요청이 닿기 전에 먼저 실행돼. 이게 핵심이야.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?
아파트 입구에 경비원이 있어. 누가 들어오든 먼저 경비원을 만나야 해.
"입주민 카드 있어요?" → 없으면 못 들어가게 막아.
"몇 동 가세요?" → 1동은 왼쪽, 2동은 오른쪽으로 안내해줘.

Middleware가 그 경비원이야. 모든 요청이 실제 페이지(아파트 각 세대)에 닿기 전에 반드시 경비원을 거쳐야 해.

Middleware의 실행 위치:

사용자 브라우저 요청
    ↓
🛡️ middleware.ts (Edge에서 실행, 가장 먼저!)
    ↓
Next.js 앱 서버
    ↓
layout.tsx → page.tsx

🧩 middleware.ts 기본 구조 — 모든 요청의 첫 관문 🟢

🎯 이 섹션을 읽고 나면:

• middleware.ts 파일을 프로젝트 루트에 만들어 모든 요청을 가로챌 수 있다
• NextResponse.redirect()와 NextResponse.next()의 차이를 안다
• matcher로 Middleware 실행 경로를 제어할 수 있다

// middleware.ts (프로젝트 루트 — app 폴더와 같은 레벨)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
 
  console.log(`[Middleware] 요청 경로: ${pathname}`)
 
  // 특정 조건에서 리디렉트
  if (pathname === '/old-posts') {
    // NextResponse.redirect: 다른 URL로 영구 보내기
    return NextResponse.redirect(new URL('/posts', request.url))
  }
 
  // 요청 헤더에 정보 추가 (페이지 컴포넌트에서 읽을 수 있음)
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-pathname', pathname)
 
  // NextResponse.next(): "통과, 다음으로 진행해"
  return NextResponse.next({
    request: { headers: requestHeaders },
  })
}
 
// ⚙️ matcher: Middleware를 실행할 경로 패턴 설정
export const config = {
  matcher: [
    // 아래 경로들을 제외한 모든 경로에서 실행
    // 이미지, 정적 파일, API 등은 보통 제외하는 게 성능에 좋음
    '/((?!_next/static|_next/image|favicon.ico|api/webhooks).*)',
  ],
}

matcher 패턴 작성법:

💡 한 줄로 기억하기
middleware.ts는 아파트 경비원. matcher는 경비원 근무 구역 지도야. 지도에 없는 곳은 그냥 통과시켜.

🔐 인증 리디렉트 패턴 — 로그인 안 한 사람 차단하기 🟡

🎯 이 섹션을 읽고 나면:

• 쿠키의 세션 토큰을 읽어 로그인 여부를 판단할 수 있다
• 로그인 안 한 사용자를 /login으로 리디렉트하는 패턴을 구현할 수 있다

🤔 잠깐, 먼저 생각해봐
세션 토큰은 쿠키에 있어. Middleware에서 쿠키를 읽어서 유효한 세션인지 어떻게 확인할 수 있을까?

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
// 로그인 없이 접근 가능한 공개 경로 목록
const PUBLIC_PATHS = ['/', '/login', '/signup', '/posts']
 
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
 
  // 공개 경로는 바로 통과
  const isPublic = PUBLIC_PATHS.some(
    (path) => pathname === path || pathname.startsWith(`${path}/`)
  )
  if (isPublic) return NextResponse.next()
 
  // 쿠키에서 세션 토큰 읽기
  const sessionToken = request.cookies.get('session')?.value
 
  // 세션이 없으면 로그인 페이지로 리디렉트
  if (!sessionToken) {
    const loginUrl = new URL('/login', request.url)
    // 로그인 후 원래 가려던 페이지로 돌아오기 위해 callbackUrl 파라미터 추가
    loginUrl.searchParams.set('callbackUrl', pathname)
    return NextResponse.redirect(loginUrl)
  }
 
  // ⚠️ 주의: Middleware는 Edge Runtime에서 돌아감
  // DB 조회나 무거운 JWT 검증은 여기서 하면 안 돼
  // 간단한 토큰 존재 여부 확인만 하고, 실제 검증은 페이지/API에서 해
  return NextResponse.next()
}
 
export const config = {
  // 정적 파일, 이미지, API는 제외
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api).*)'],
}

이 패턴의 한계와 올바른 역할 분리:

Middleware (Edge)    → "토큰이 있는가?" 만 확인 (빠른 1차 체크)
    ↓ 통과
페이지 / Server Action → "토큰이 유효한가? 권한이 있는가?" 심층 검증 (느리지만 정확)

⚠️ 주의: Middleware에서 DB 쿼리나 복잡한 암호화 연산을 하면 안 돼. Edge Runtime은 Node.js API 일부가 제한되어 있고, 모든 요청마다 실행되므로 성능에 직결돼.

🔗 연결 고리
세션 검증의 심층 패턴 (DAL, verifySession())은 심화 7장 Authentication Architecture에서 자세히 다뤄. 지금은 Middleware의 1차 관문 역할만 파악하면 충분해.

🌍 Edge Runtime이란 무엇인가 🟡

🎯 이 섹션을 읽고 나면:

• Edge Runtime과 Node.js Runtime의 차이를 설명할 수 있다
• Middleware에서 사용할 수 없는 Node.js API가 무엇인지 알고 대안을 찾을 수 있다

📖 용어: Edge Runtime — 사용자에게 가장 가까운 CDN 엣지 서버에서 코드를 실행하는 환경이야. 일반 서버(Origin)까지 요청이 닿지 않아도 되니까 레이턴시가 훨씬 낮아.

일반 Node.js 서버
사용자(서울) → 서버(미국) → 응답 반환  [레이턴시: 200ms+]

Edge Runtime
사용자(서울) → 서울 엣지 노드 → 응답 반환  [레이턴시: 10ms 이하]

Edge Runtime에서 사용할 수 없는 것들:

// ❌ Middleware에서 쓰면 안 되는 패턴
import bcrypt from 'bcrypt'     // Node.js 전용 — Edge에서 에러!
import { PrismaClient } from '@prisma/client'  // TCP 소켓 — Edge에서 에러!
 
// ✅ Middleware에서 쓸 수 있는 패턴
import { jwtVerify } from 'jose'   // Web Crypto API 기반 — Edge 호환!
const token = request.cookies.get('session')?.value  // Web API — Edge 호환!

💡 한 줄로 기억하기
Edge Runtime은 "초경량 실행 환경"이야. 빠른 대신 Node.js의 무거운 기능을 못 써. Middleware는 여기서 돌아가니 가볍게 써야 해.

🔒 보안 헤더 설정 — CSP와 HSTS 🔴

🎯 이 섹션을 읽고 나면:

• Middleware에서 모든 응답에 보안 헤더를 자동으로 추가하는 패턴을 구현할 수 있다

Middleware는 모든 응답에 헤더를 추가하기에 완벽한 위치야.

// middleware.ts — 보안 헤더 설정 패턴
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  const response = NextResponse.next()
 
  // XSS 방어: 브라우저가 Content-Type을 무시하지 못하게 강제
  response.headers.set('X-Content-Type-Options', 'nosniff')
 
  // 클릭재킹 방어: 다른 사이트의 iframe에서 우리 페이지 임베드 금지
  response.headers.set('X-Frame-Options', 'DENY')
 
  // HTTPS 강제: 1년간 HTTPS만 허용 (HSTS)
  response.headers.set(
    'Strict-Transport-Security',
    'max-age=31536000; includeSubDomains'
  )
 
  // CSP: 스크립트·이미지·폰트 소스 화이트리스트
  response.headers.set(
    'Content-Security-Policy',
    [
      "default-src 'self'",
      "script-src 'self' 'unsafe-inline'",   // Next.js inline script 허용
      "img-src 'self' data: https:",
      "font-src 'self' https://fonts.gstatic.com",
    ].join('; ')
  )
 
  return response
}

💥 에러 해결 카탈로그

❌ require() of ES modules is not supported

언제 나오는가?

Error: require() of ES Module ... not supported.

원인: Middleware(Edge Runtime)에서 CommonJS 모듈을 import했을 때. bcrypt, jsonwebtoken 같은 패키지가 주범.

해결책:

// ❌ 에러 발생
import jwt from 'jsonwebtoken'  // CJS 패키지
 
// ✅ Edge 호환 대안
import { jwtVerify, SignJWT } from 'jose'  // Web Crypto API 기반

❌ Middleware가 정적 파일 요청에도 실행되어 느려짐

원인: matcher를 설정하지 않아 CSS, JS, 이미지 파일 요청에도 Middleware가 실행됨.

해결책:

export const config = {
  matcher: [
    // _next 하위 정적 파일과 favicon은 제외
    '/((?!_next/static|_next/image|favicon.ico).*)',
  ],
}

🏁 이번에 배운 내용 총정리

📋 핵심 명령 패턴

⚠️ 절대 하지 말 것

📝 마무리 퀴즈

Q1. Middleware는 요청 흐름에서 언제 실행될까?

✅ 정답: 라우트 로직에 도달하기 전 Edge에서 먼저 실행된다.

💡 상세 해설: 그래서 리다이렉트, 간단한 인증 존재 확인, 지역/언어 분기처럼 빠른 판단에 적합하다.

Q2. Middleware에 무거운 DB 권한 검사를 넣으면 왜 위험할까?

✅ 정답: Edge Runtime 제약과 성능 비용 때문에 모든 요청의 병목이 될 수 있다.

💡 상세 해설: Middleware는 넓게 실행된다. 정밀한 권한과 소유권 검사는 서버의 DAL이나 Route Handler/Server Action에서 다시 확인하는 편이 안전하다.

Q3. 영철이의 테스트 타임: /admin 접근을 막아야 한다. Middleware만으로 충분할까?

✅ 정답: 아니다. Middleware는 1차로 걸러내고, 실제 데이터 변경 지점에서 role을 다시 확인해야 한다.

💡 상세 해설: URL 접근 차단은 좋은 시작이지만 직접 요청이나 내부 호출까지 막지는 못한다. 보안은 여러 경계가 겹쳐야 한다.

🐣 영철이의 퇴근 일기

오늘은 Middleware를 모든 보안 로직을 넣는 장소로 착각하지 않게 됐다.

💡 "Edge에서는 빠르게 거르고, 서버에서는 정확하게 검증한다."

앞으로 matcher 범위와 DAL 권한 검사를 한 쌍으로 리뷰하겠다.

🔗 더 알아보기

• Next.js 공식 문서 — Middleware
• Edge Runtime 지원 API 목록
• jose 라이브러리 (Edge 호환 JWT)

🔗 더 알아보기

• Next.js 공식 문서 — Middleware
• Edge Runtime 지원 API 목록
• jose 라이브러리 (Edge 호환 JWT)