넥스트 16에서 요청 앞 파일은 proxy.ts이고 함수 이름도 proxy여야 합니다. 파일만 바꾸면 로그인 이동이 조용히 사라집니다. 엣지가 필요할 때만 예전 파일을 남기고, 매처가 경로를 빼먹는 문제와는 자리를 가릅니다. 설정 키의 예전 이름은 같이 바꿉니다. Next.js, 프론트, 한국 1인 개발. 2026년 9월 16.3 문서.
proxy.ts로 파일만 바꾸고 함수 이름이 예전 그대로면, 넥스트 16은 그 함수를 요청 앞에서 실행하지 않습니다. 파일 이름과 함수 이름을 같이 맞춰야 리다이렉트가 돕니다.
16으로 올린 뒤 로그인 이동이 조용히 사라지는 일이 있습니다. 함수를 그대로 두면 빌드가 초록이어도 분기는 비어 있습니다. 매처가 경로를 빼먹는 문제와는 자리가 다릅니다.
예전 파일을 proxy.ts로 바꾸고 함수도 proxy로 고칩니다. 엣지가 꼭 필요하면 폐기 예정인 예전 파일을 당분간 유지합니다. 근거는 이전 문서와 Next.js 16 발표입니다.
요청이 앱에 들어가기 전에 도는 경계라서 이름을 바꿨습니다. 넥스트 16 발표는 2025년 10월 21일에 middleware.ts를 proxy.ts로 바꿔 네트워크 경계를 분명히 한다고 적습니다. 동작의 큰 줄은 같고, 파일 규칙과 런타임 설명이 달라졌습니다.
공식 오류 문서는 middleware 파일 규칙이 폐기되었고 이름이 proxy로 바뀌었다고 합니다. 익스프레스의 미들웨어처럼 요청마다 아무 일이나 넣으라는 뜻이 아니라는 설명입니다. 느린 데이터 조회나 완전한 로그인 세션 저장소로 쓰지 말라고 입문 문서가 적습니다.
그래서 16 업그레이드 직후 "파일은 있는데 분기가 안 탄다"면 런타임 예외보다 파일 이름을 먼저 봅니다. 빌드가 초록이어도 예전 파일만 남아 있으면 그 함수는 새 규칙의 진입점이 아닙니다.
먼저 맞출 것 | 파일 이름이 proxy.ts 이고, 이름 있는 export도 proxy 인지 두 칸을 같이 보세요. 둘 중 하나만 바꾸면 요청 앞 분기가 비어 있습니다.
코드모드와 수동 이전 모두 함수 이름을 바꿉니다. 문서는 middleware.ts를 proxy.ts로 바꾸고, export function middleware를 export function proxy로 바꾸라고 합니다. 기본보내기만 쓰는 경우에도 함수 이름을 proxy로 두는 쪽을 권합니다.
파일 위치는 예전과 같습니다. 프로젝트 루트, 또는 src를 쓰면 src 안에 두고 app이나 pages와 같은 높이입니다. 프로젝트당 proxy 파일은 하나입니다. 분기가 길면 다른 모듈로 나누고, 파일은 하나에서 그 함수를 부릅니다.
업그레이드 코드모드는 가이드에 middleware-to-proxy 로 올라 있습니다. 파일 이름, 함수 이름, 설정 키의 middleware 접두어를 같이 바꿉니다. 손으로 옮길 때는 아래 두 줄이면 리다이렉트 예시가 다시 탑니다.
파일과 함수를 같이 바꾸기# 루트 또는 src 옆 mv middleware.ts proxy.ts # proxy.ts # export function proxy(request) { # return NextResponse.redirect(new URL('/home', request.url)) # } # export const config = { matcher: '/about/:path*' }
프록시 런타임은 노드이고, 엣지로 바꿀 수 없습니다. 16 발표는 proxy.ts가 노드 런타임에서 돈다고 적고, 업그레이드 문서는 엣지 런타임이 프록시에서 지원되지 않는다고 합니다. 엣지가 아직 필요하면 middleware.ts를 유지합니다. 그 파일은 폐기 예정이고 이후 버전에서 빠질 수 있다고 발표가 적습니다.
두 파일을 역할 없이 같이 두면 어느 쪽이 요청을 받는지 리뷰가 어려워집니다. 노드로 충분한 리다이렉트와 헤더 수정은 proxy.ts 하나로 옮기고, 엣지가 필요한 경우만 예전 파일에 이유를 주석으로 남기세요. 주석은 짧게, 왜 엣지인지 한 줄이면 됩니다.
지역이 가까운 엣지에서만 되던 분기를 노드 프록시로 옮기면 지연이 달라질 수 있습니다. 동작이 사라졌는지와 느려졌는지는 따로 보세요. 사라진 것은 함수 이름이고, 느려진 것은 런타임 위치입니다.
| 파일 | 16에서 | 런타임 |
|---|---|---|
| proxy.ts | 현재 규칙 | 노드, 변경 불가 |
| middleware.ts | 폐기, 당분간 남음 | 엣지가 필요할 때 |
| 함수 이름 middleware | 이름 있는 export는 폐기 | proxy로 변경 |
| 둘을 동시에 | 역할을 나누지 않으면 혼란 | 엣지 이유만 예전 파일 |
경로를 고르는 config.matcher 는 그대로 둡니다. 입문 문서의 예도 export const config = { matcher: '/about/:path*' } 를 proxy 함수 옆에 둡니다. 매처가 관리자 경로나 서버 액션을 빼먹는 문제는 파일 이름과 별개입니다. 그 칸은 매처와 서버 액션 글을 보면 됩니다.
설정 키 가운데 middleware가 들어간 이름은 바뀌었습니다. skipMiddlewareUrlNormalize 는 skipProxyUrlNormalize 입니다. 공식 설정 문서는 둘을 동시에 두면 오류가 난다고 합니다. 예전 이름만 있으면 폐기 경고가 나고, 코드모드가 키를 바꿔 줍니다.
본문 크기 한도 키도 이름에 middleware가 있었다면 proxy 쪽으로 바뀝니다. 업로드가 413으로 죽는 현상 자체는 서버 액션 본문 한도의 자리입니다. 여기서는 키 이름이 업그레이드 때 같이 바뀌는지만 확인하면 됩니다.
설정 키를 프록시 이름으로// next.config 안에서 둘을 같이 두지 않는다 const nextConfig = { skipProxyUrlNormalize: true, } // 예전 이름 skipMiddlewareUrlNormalize 는 폐기 경고
프록시는 요청을 보고 리다이렉트, 리라이트, 헤더 수정, 짧은 응답을 하는 자리입니다. 입문 문서는 권한에 따른 낙관적 이동은 가능해도, 세션 관리 전체를 여기 두지 말라고 합니다. 쿠키를 읽어 정적 빌드가 멈추는 문제는 페이지의 cookies() 쪽이라 정적 생성과 쿠키 글과 다릅니다.
클릭 핸들러를 서버 컴포넌트에서 넘기다 막히는 줄도 이 파일이 고치지 않습니다. 그 오류는 클라이언트 경계의 직렬화라 이벤트 핸들러를 넘기는 글을 보면 됩니다. 브라우저가 다른 출처를 막는 줄은 CORS입니다. 프록시가 헤더를 붙여도 출처 허용의 본문은 API 응답에 있어야 합니다.
fetch의 cache 옵션은 프록시 안에서 기대한 캐시로 동작하지 않는다고 입문 문서가 적습니다. 느린 조회는 페이지나 라우트 핸들러로 내리고, 프록시는 주소와 헤더만 만집니다. 한국에서 혼자 프리뷰 도메인으로 로그인 이동을 거는 경우에도, 허용 출처 목록은 환경 변수로 읽고 분기는 짧게 유지하면 파일 업그레이드가 안전합니다.
| 증상 | 칸 | 볼 글 |
|---|---|---|
| 이동이 조용히 사라짐 | 파일, 함수 이름 | 이 글 |
| 일부 경로만 통과 | matcher | 매처와 서버 액션 |
| 빌드가 쿠키에서 멈춤 | 페이지 cookies() | 정적 생성 |
| onClick을 넘기다 실패 | 서버에서 클라이언트로 함수 | 이벤트 핸들러 |
내부 연계: 매처와 서버 액션, 쿠키와 정적 생성, 이벤트 핸들러, CORS 프리플라이트
파일 규칙은 2026년 9월 Next.js 16.3 문서와 2025년 10월 16 발표 기준입니다.
이름 있는 함수가 아직 middleware이면 새 규칙의 진입점이 아닙니다. export function proxy 로 바꾸고, 기본보내기라도 함수 이름을 proxy로 두세요. 매처가 그 경로를 포함하는지도 이어서 확인합니다.
16 문서 기준으로 프록시 런타임은 노드이고 엣지로 설정할 수 없습니다. 엣지가 필요하면 폐기 예정인 middleware.ts를 유지합니다. 이후 버전에서 그 파일이 빠지기 전에 노드로 옮길 수 있는지 따로 보면 됩니다.
경로를 고르는 config.matcher 예는 그대로입니다. 바뀐 것은 파일 이름, 함수 이름, skipMiddlewareUrlNormalize 같은 설정 키입니다. 특정 경로만 빠지는 문제는 매처 표현을 보면 됩니다.
src/proxy.ts 처럼 app 또는 pages와 같은 높이에 둡니다. 프로젝트당 파일은 하나입니다. pages 안에 넣으면 규칙으로 인식되지 않습니다.
쿠키를 보고 로그인 페이지로 보내는 짧은 분기는 흔합니다. 세션 저장과 권한의 본검사는 페이지나 서버 함수에 두라고 입문 문서가 적습니다. 프록시 안의 fetch 캐시 옵션은 기대한 대로 동작하지 않습니다.
이 파일 이름 변경은 16부터입니다. 15를 유지하는 동안에는 middleware.ts가 그 버전의 규칙입니다. 16으로 올리는 커밋에서 파일과 함수와 설정 키를 같이 바꾸면 됩니다.
