Proxy

김동현·2026년 3월 4일

next.js 공식문서 번역

목록 보기

16/79

Proxy (프록시)

알아두면 좋은 점: Next.js 16부터는 미들웨어(Middleware)가 그 목적을 더 잘 나타내기 위해 프록시(Proxy)라는 이름으로 변경되었어요. 기능 자체는 기존과 동일하답니다!

👨‍🏫 강사의 부연 설명 & 팁 💡:
이전에 Next.js를 공부해보셨다면 '미들웨어'라는 단어가 익숙하실 거예요! 기능은 똑같은데 이름만 Proxy로 바뀌었답니다. 클라이언트(브라우저)와 서버 사이에 문지기처럼 서서 요청을 미리 가로채는 역할을 해요. 나중에 실무 면접에서 "Next.js 16의 Proxy가 이전 버전의 어떤 기능인가요?"라는 질문을 받으시면 당황하지 말고 미들웨어라고 자신 있게 대답하시면 됩니다.

프록시를 사용하면 요청(request)이 완료되기 전에 코드를 실행할 수 있어요. 그런 다음 들어오는 요청에 따라 요청이나 응답의 헤더를 재작성(rewriting), 리다이렉션, 수정하거나 아예 직접 응답을 내려주는 방식으로 응답을 마음대로 변경할 수 있답니다.

사용 사례 (Use cases)

프록시가 아주 효과적으로 쓰이는 일반적인 상황들은 다음과 같아요:

모든 페이지 또는 특정 페이지의 헤더(headers) 수정하기
A/B 테스트나 실험에 따라 다른 페이지로 재작성(Rewriting)하기
들어오는 요청의 속성에 따라 프로그래밍 방식으로 리다이렉트(Redirect)하기

👨‍🏫 강사의 부연 설명 & 팁 💡:
예를 들어, 사용자의 브라우저 언어 설정(Accept-Language 헤더)을 프록시에서 읽어서 한국어/영어 페이지로 자동 리다이렉트 시켜주거나, 권한이 없는 사용자가 특정 문서를 보려고 할 때 로그인 페이지로 튕겨내는 기능을 구현해두면 기술적으로 아주 매력적인 포트폴리오가 될 거예요!

단순한 리다이렉트가 필요하다면, 먼저 next.config.ts 파일에서 redirects 설정을 사용하는 걸 우선적으로 고려해보세요. 프록시는 요청 데이터에 직접 접근해야 하거나 더 복잡한 로직이 필요할 때 사용하는 것이 맞습니다.

프록시는 느린 데이터 패칭(slow data fetching)을 위해 만들어진 게 아니에요. 권한 기반 리다이렉트 같은 낙관적 확인 (optimistic checks)에는 프록시가 도움이 될 수 있지만, 이걸 완벽한 세션 관리나 인가(authorization) 솔루션으로 사용해서는 안 됩니다.

👨‍🏫 강사의 부연 설명 💡:
주의하셔야 할 부분입니다! 프록시는 Edge 런타임이라는 아주 가볍고 빠른 환경에서 동작해요. 만약 여기서 무거운 DB 쿼리를 돌리거나 응답이 느린 외부 API를 호출해버리면, 사용자가 화면을 보기도 전에 병목이 생겨버립니다. 무거운 인증 로직이나 데이터 패칭은 서버 컴포넌트나 백엔드 API에서 처리하는 것이 프론트엔드 성능 최적화의 핵심이에요.

프록시 안에서 options.cache, options.next.revalidate, 또는 options.next.tags와 함께 fetch를 사용하는 건 아무런 효과가 없어요.

규칙 (Convention)

프로젝트 루트 디렉토리나 (사용 중이라면) src 폴더 안에 proxy.ts (또는 .js) 파일을 만드세요. 즉, pages나 app 폴더와 같은 레벨에 위치해야 합니다.

참고: 프로젝트당 단 하나의 proxy.ts 파일만 지원되지만, 프록시 로직을 여러 모듈로 예쁘게 정리할 수는 있어요. 프록시 기능들을 별도의 .ts나 .js 파일로 쪼갠 다음, 메인 proxy.ts 파일로 불러와서(import) 사용하세요. 이렇게 하면 라우트별 프록시를 더 깔끔하게 관리할 수 있고, 중앙 제어를 위해 proxy.ts 하나에 모아둘 수 있습니다. 프록시 파일을 단 하나로 강제함으로써 설정을 단순화하고, 발생할 수 있는 충돌을 방지하며, 여러 프록시 레이어를 거치지 않게 해 성능을 최적화할 수 있답니다.

예시 (Example)

프록시 함수는 기본 내보내기(default export) 또는 proxy라는 이름의 내보내기(named export) 중 하나로 내보낼 수 있어요:

// filename="proxy.ts" switcher
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// This function can be marked `async` if using `await` inside
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// Alternatively, you can use a default export:
// export default function proxy(request: NextRequest) { ... }

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

// filename="proxy.js" switcher
import { NextResponse } from 'next/server'

// This function can be marked `async` if using `await` inside
export function proxy(request) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// Alternatively, you can use a default export:
// export default function proxy(request) { ... }

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