Next.js 16의 Proxy

`middleware.ts`가 `proxy.ts`로 바뀌었어

Next.js 16에서는 파일 이름이 middleware.ts에서 proxy.ts로, 내보내는 함수 이름도 middleware()에서 proxy()로 바뀌었어. 기본 실행 환경은 15.5부터 Edge가 아니라 Node.js야. 오래된 예제를 그대로 복사하면 이름과 런타임 가정이 함께 어긋날 수 있어.

프로젝트 루트에서 라우트보다 먼저 실행돼

proxy.ts는 app/ 옆 프로젝트 루트에 두고, matcher 설정과 맞는 요청마다 라우트 렌더링 전에 실행해. 리디렉션, 재작성, 요청 헤더 보강처럼 네트워크 입구에서 결정할 일을 맡아.

새 이름이 실제 위치를 더 잘 말해

옛 이름은 React 렌더링의 중간에서 동작하는 것처럼 들렸지만, 실제로는 네트워크와 라우트 사이에 앉은 역방향 프록시에 가까워. 새 이름은 그 경계를 드러내려는 변경이야. 공식 codemod로 파일과 함수 이름을 함께 옮길 수 있어.

모든 인증 로직을 여기에 몰지는 마

Proxy는 빠른 UX 차단에 좋지만 최종 데이터 권한 검사를 대신하지 않아. 직접 POST와 다른 실행 경로는 서버 액션이나 라우트 핸들러에서 다시 지켜야 해.

업그레이드할 때 공식 codemod로 이름을 바꾼 뒤 matcher, import, 런타임 의존성을 검토해. Edge에서 Node.js로 옮기며 새로 가능한 API가 있지만 실행 위치와 지연도 달라질 수 있어. 배포 로그에서 Proxy가 실제로 어떤 경로에 몇 번 실행되는지 확인해.

이름이 Proxy로 바뀌었다고 범용 backend가 된 건 아니야. 모든 요청 앞에 놓이므로 느린 DB query와 복잡한 비즈니스 로직은 사이트 전체 지연과 장애 범위를 키워. 빠른 분기와 헤더 조작만 남기고 데이터 권한은 더 깊은 경계에서 검사해. 옛 middleware 파일을 codemod로 옮기고 변경 diff에서 파일·함수 이름과 runtime 의존성을 확인해. matcher에 포함·제외된 URL을 curl로 호출해 헤더와 redirect를 비교하고, 정적 자산 요청 수가 Proxy 실행 로그에 나타나지 않게 범위를 조정해. matcher가 정적 파일과 이미지 요청을 빼는지 목록으로 시험하고, Proxy를 우회한 직접 호출도 가장 깊은 권한 검사에서 막히는지 확인해.

Code

프로젝트 루트의 proxy.ts·ts

// proxy.ts
import { NextRequest, NextResponse } from 'next/server';

export function proxy(request: NextRequest) {
  const session = request.cookies.get('session')?.value;
  if (!session && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*'],
};

matcher 설정·ts

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/:path*',
    // 정적 파일과 이미지 자산은 건너뛰어
    '/((?!_next/static|_next/image|favicon.ico).*)',
  ],
};

`middleware.ts`가 `proxy.ts`로 바뀌었어

프로젝트 루트에서 라우트보다 먼저 실행돼

새 이름이 실제 위치를 더 잘 말해

모든 인증 로직을 여기에 몰지는 마

Code

External links

Exercise

Progress

댓글 0

middleware.ts가 proxy.ts로 바뀌었어

프로젝트 루트에서 라우트보다 먼저 실행돼

새 이름이 실제 위치를 더 잘 말해

모든 인증 로직을 여기에 몰지는 마

Code

External links

Exercise

Progress

`middleware.ts`가 `proxy.ts`로 바뀌었어