#26. middleware / proxy

1) 개념: “Middleware”와 “Proxy”는 뭐가 다른가요?

공통점(역할은 동일)

둘 다 요청이 페이지/라우트 핸들러로 도착하기 전에 서버(주로 Edge)에서 먼저 실행되어,

• redirect / rewrite
• 요청/응답 헤더 수정
• 요청을 차단하고 직접 응답 반환

같은 “문지기(게이트)” 역할을 합니다. Next.js

차이점(Next.js 16에서 이름/컨벤션이 변경)

• Next.js 16부터 기존 middleware.ts 파일 컨벤션이 deprecated 되었고, proxy.ts로 이름이 변경되었습니다. (기능이 바뀐 게 아니라 “명명/컨벤션”이 바뀐 것) Next.js+2Next.js+2
• Next.js 16 블로그에서도 middleware.ts는 당장은 동작하지만 deprecated이며, 미래 버전에서 제거될 예정이라고 안내합니다. Next.js

---

2) 파일 위치/이름 규칙

Next.js 16 (권장)

• proxy.ts 또는 proxy.js
• 위치: 프로젝트 루트 또는 /src 바로 아래 Next.js+1

예)

/proxy.ts /src/proxy.ts

 

 

Next.js 15 이하 (기존 방식)

• middleware.ts 또는 middleware.js
• 위치: 동일(루트 또는 src) Next.js+1

---

3) 함수(export) 이름도 바뀝니다 (v16 핵심)

v16: proxy.ts에서는 proxy를 export

// proxy.ts
import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";

export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL("/", request.url));
}

export const config = {
  matcher: ["/profile", "/profile/:path*"],
};

 

Proxy 시작 가이드는 이런 형태의 proxy 예시와 matcher 사용을 안내합니다. Next.js

(참고) v15 이하: middleware.ts에서는 middleware export

 

export function middleware(request: NextRequest) { ... }

 

기존 문서에서는 middleware export 형태를 안내합니다. Next.js+1

---

4) matcher(config)로 “어떤 경로에만 적용할지” 제어

• config.matcher는 Proxy/Middleware가 실행될 경로를 필터링합니다. Next.js+1
• 실무에서는 보통 다음처럼 “서브 경로까지” 같이 잡습니다.

 

export const config = {
  matcher: ["/profile", "/profile/:path*"],
};

 

---

5) Proxy/Middleware로 할 수 있는 대표 패턴

A. 특정 경로 접근 시 강제 리다이렉트

• /profile → /로 보내기 (질문 주신 케이스)

B. 인증/권한 가드

• 쿠키/헤더를 보고 로그인 안 됐으면 /login으로 redirect
• 또는 401 JSON 직접 반환

단, 쿠키/헤더 기반 인증은 매우 흔한 패턴입니다. Next.js+1

C. 헤더 추가로 “서버-렌더/라우트”에 정보 전달

• Proxy에서 x-tenant, x-country 같은 헤더를 붙여서 뒤 로직에서 분기
• “공유 변수/글로벌”을 기대하지 말고 헤더/쿠키/URL로 전달하라고 문서에서도 안내합니다. Next.js

---

6) 주의사항(제약): Edge Runtime 성격

Proxy(기존 Middleware)는 “요청 초입”에서 빠르게 처리하기 위한 레이어라 보통 Edge Runtime 기반 제약이 있습니다. 예를 들어:

• 파일 시스템 접근 등 Node.js 네이티브 API 사용 불가
• require 직접 호출 불가(ESM 사용)
• 사용 가능한 라이브러리도 “Edge 호환”이어야 함 Next.js

(그래서 인증 JWT 검증도 Edge 호환 방식으로 하거나, 필요한 경우 API로 위임하는 구조가 자주 나옵니다.)

---

7) 정리

• Next.js 15 이하: middleware.ts + export function middleware
• Next.js 16: proxy.ts + export function proxy (기존 middleware 컨벤션은 deprecated) Next.js+2Next.js+2