🚀 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에서 절대로 하면 안 되는 것은?

• A) 쿠키에서 세션 토큰 값 읽기
• B) 특정 경로로 리디렉트하기
• C) Prisma로 데이터베이스 조회하기
• D) 응답 헤더에 보안 헤더 추가하기

✅ 정답: C

오답 해설:

• A, D — 쿠키 읽기, 헤더 추가는 Edge 호환 작업
• B — 리디렉트는 Middleware의 핵심 기능 중 하나
• C — Prisma는 TCP 소켓 의존. Edge Runtime에서 불가

📌 핵심 기억법: Middleware는 "가볍게, 빠르게, DB 없이."

Q2. 아래 빈칸을 채워보자.

로그인 페이지(/login)는 세션 없이도 접근 가능해야 한다. 빈칸을 채워 올바른 matcher를 완성해.

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|______).*)'],
}

✅ 정답: login (또는 login|signup|api)

해설: 공개 경로들은 matcher에서 제외해 Middleware가 실행되지 않게 하거나, Middleware 내부에서 PUBLIC_PATHS 배열로 통과 처리해야 해.

Q3. 친구에게 설명한다면?

Middleware와 각 페이지 컴포넌트 안에서 인증 체크를 하는 것의 차이를 비유로 설명해봐.

예시 답변:

"Middleware는 건물 입구 경비원이야. 들어오는 모든 사람을 한 번에 체크해. 반면 각 페이지에서 체크하는 건 각 방마다 경비원을 세우는 거야. 100개 방이면 100명. Middleware 하나로 전부 막는 게 훨씬 효율적이지."

🐣 영철이의 퇴근 일기

오늘은 정말 든든한 '요새 경비원(Middleware)'을 고용한 날이야! 페이지가 늘어날 때마다 "로그인 체크 코드를 또 어디에 복붙해야 하지?" 고민하며 머리가 아팠는데, 한 곳에서 모든 출입을 통제할 수 있다는 게 얼마나 큰 축복인지 깨달았어.

💡 오늘의 교훈: "모든 방마다 경비원을 세우지 말고 건물 입구(Middleware)를 지키자. Edge 환경은 가볍고 빠르게 유지하는 것이 생명이다!"

Edge Runtime이라는 생소한 환경에서 Prisma 같은 무거운 도구를 못 써서 조금 당황하긴 했지만, 오히려 그 덕분에 "어떤 코드가 가볍고 빠른 코드인가"에 대해 깊게 생각해보는 계기가 됐어. 오늘 하루 참 보람찼다! 집에 가서 시원한 캔맥주 하나 따고 영화나 한 편 보면서 금요일 분위기 내야지. 내일은 더 '가볍고 강력한' 로직을 짜는 개발자가 되어야겠어. 🐣

🔗 더 알아보기

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