Next.js (16. Proxy) 정리

0. Proxy

---

Proxy는 요청이 완료되기 전에 코드를 실행해 응답을 제어하는 기능이다. Next.js 16부터 Middleware가 Proxy로 이름이 변경되었으며, 기능은 동일하다.

들어오는 요청을 기반으로 다음 작업을 수행할 수 있다.

• 리라이트(Rewriting): 다른 경로로 요청을 전달한다.
• 리다이렉트(Redirecting): 다른 URL로 응답을 보낸다.
• 헤더 수정: 요청 또는 응답 헤더를 변경한다.
• 직접 응답: Proxy에서 바로 응답을 반환한다.

1. 사용 사례와 제약

---

Proxy가 효과적인 시나리오는 요청 데이터에 접근하거나 복잡한 로직이 필요한 경우다.

주요 사용 사례:

• 모든 페이지 또는 특정 페이지에 헤더 추가/수정
• A/B 테스트나 실험에 따라 다른 페이지로 리라이트
• 요청 속성 기반의 프로그래밍 방식 리다이렉트

단순 리다이렉트는 Proxy 대신 next.config.ts의 redirects 설정을 먼저 고려한다.

• Proxy는 느린 데이터 페칭에 사용하면 안 된다.
• 전체 세션 관리나 인가(authorization) 솔루션으로 사용하면 안 된다.
• fetch의 options.cache, options.next.revalidate, options.next.tags는 Proxy 내에서 효과가 없다.

2. 사용 방법

---

2-1. 파일 위치와 규칙

---

proxy.ts 파일을 프로젝트 루트 또는 src 폴더 안에 생성한다. pages 또는 app 폴더와 같은 레벨에 위치해야 한다.

프로젝트당 하나의 proxy.ts 파일만 지원된다. 로직은 별도 모듈로 분리하고 proxy.ts에서 import해 관리한다.

2-2. 기본 예시 — matcher 설정

---

proxy 함수를 named export 또는 default export로 내보내고, config.matcher로 적용할 경로를 지정한다.

// proxy.ts

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// await를 사용하는 경우 async로 선언할 수 있다
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// default export도 사용 가능:
// export default function proxy(request: NextRequest) { ... }

export const config = {
  matcher: '/about/:path*',
}

matcher는 Proxy가 실행될 특정 경로를 필터링한다. /about/:path*는 /about으로 시작하는 모든 경로에 Proxy를 적용한다.