Next.js middleware가 deprecated라면, proxy.ts로 바꾸기 전 확인할 것

Next.js 16으로 올린 뒤 middleware.ts가 deprecated라는 경고가 보이면 파일명부터 바꾸고 싶어진다. 하지만 경고를 지우는 것보다 기존 redirect와 header 동작을 지키는 일이 먼저다. 설치된 Next.js 버전, Edge Runtime 의존, middleware가 맡은 일을 확인한 뒤 proxy.ts 전환 여부를 정해야 한다.

전환 조건이 맞으면 공식 codemod나 수동 변경으로 파일명과 함수 이름을 함께 바꾼다. 마지막에는 npm run build만 보지 말고 matcher가 가리키는 실제 경로까지 열어야 한다. 이 순서를 지키면 AI에게 수정을 맡겨도 “경고가 사라졌다”가 아니라 “기존 요청 처리가 유지됐다”는 결과를 남길 수 있다.

Tap to zoom

파일명을 바꾸기 전에 세 가지를 확인한다

Next.js 공식 Proxy 문서는 버전 16부터 Middleware를 Proxy라고 부른다. 요청이 완료되기 전에 redirect, rewrite, header 변경 같은 처리를 수행하는 기능 자체는 이어진다. 이름이 바뀐 이유는 이 코드가 앱 앞의 네트워크 경계에서 실행된다는 역할을 더 분명하게 드러내기 위해서다.

먼저 현재 버전을 확인한다.

npm ls next

이 명령은 프로젝트에 실제 설치된 Next.js 버전을 보여 준다. package.json의 범위만 보고 판단하면 lockfile에 설치된 버전과 다를 수 있다.

다음으로 middleware.ts 또는 src/middleware.ts에서 runtime과 처리 목적을 확인한다.

rg -n "runtime|matcher|NextResponse|redirect|rewrite|headers" middleware.ts src/middleware.ts

Windows PowerShell에서 rg가 없다면 아래 명령으로 같은 단서를 찾을 수 있다.

Get-ChildItem middleware.ts,src/middleware.ts -ErrorAction SilentlyContinue |
  Select-String -Pattern "runtime|matcher|NextResponse|redirect|rewrite|headers"

여기서 판단은 세 갈래다.

1. Edge Runtime 의존이 있다면 바로 바꾸지 않는다. Next.js 16 업그레이드 문서는 proxy가 Node.js runtime에서 동작하며 Edge Runtime을 지원하지 않는다고 안내한다.
2. 단순한 고정 redirect만 처리한다면 next.config.ts의 redirects로 옮길 수 있는지 먼저 본다. 공식 Proxy 문서도 단순 redirect에는 이 설정을 우선 고려하라고 설명한다.
3. 요청의 cookie, pathname, header처럼 요청 시점 정보가 필요하면 Proxy 전환 후보가 된다.

Tap to zoom

자동 변경은 diff를 보기 위한 출발점이다

공식 codemod를 쓰면 파일명만이 아니라 named export와 관련 설정 이름도 함께 바뀐다.

npx @next/codemod@latest middleware-to-proxy .

이 명령은 middleware.ts를 proxy.ts로 바꾸고 export function middleware를 export function proxy로 바꾼다. skipMiddlewareUrlNormalize처럼 설정명에 middleware가 들어간 항목도 현재 Proxy 이름으로 옮긴다.

실행 전에는 작업 트리가 깨끗한지 확인한다.

git status --short

실행 뒤에는 AI나 codemod의 성공 메시지보다 실제 diff를 본다.

git diff -- middleware.ts proxy.ts src/middleware.ts src/proxy.ts next.config.*

수동으로 바꾼다면 최소 변경은 다음과 같다.

- // middleware.ts
- export function middleware(request: NextRequest) {
+ // proxy.ts
+ export function proxy(request: NextRequest) {
    return NextResponse.next()
  }

proxy.ts는 프로젝트 루트에 둔다. src 구조를 쓰면 app 또는 pages와 같은 높이의 src/proxy.ts에 둔다. 프로젝트당 Proxy 파일은 하나만 지원하므로 경로별 로직은 별도 모듈로 나누고 한 파일에서 불러온다.

AI 코딩 도구에 맡길 때는 파일명만 바꾸라고 하지 않는다. 아래처럼 변경 범위와 검증 결과를 함께 요구한다.

Next.js 16 기준으로 middleware.ts를 proxy.ts로 옮겨 주세요.
먼저 Edge Runtime 의존과 matcher를 확인하세요.
파일명, export 함수명, 관련 next.config 설정만 최소 변경하세요.
변경 뒤 git diff 요약과 npm run build 결과를 보여 주세요.
matcher 대상 redirect와 header 동작을 확인할 테스트 경로도 적어 주세요.

변경 범위를 먼저 묶는 습관은 AI가 파일을 너무 많이 고칠 때 수정 범위를 확인하는 방법에도 그대로 적용할 수 있다.

빌드와 실제 요청 경로를 둘 다 검증한다

타입 오류와 파일 convention 오류는 프로덕션 빌드에서 먼저 잡는다.

npm run build

빌드가 통과해도 matcher가 예상 경로를 포함하는지는 별도 문제다. 개발 서버를 켜고 redirect, rewrite, header 중 이 코드가 맡은 동작을 실제 URL에서 확인한다.

npm run dev

예를 들어 /dashboard/:path*를 로그인 경로로 보내는 코드라면 브라우저 시크릿 창에서 /dashboard를 연다. 응답 header를 바꾸는 코드라면 개발자 도구 Network 패널이나 curl -I로 값을 확인한다.

curl -I http://localhost:3000/dashboard

Tap to zoom

확인은 다음 순서로 닫는다.

• npm ls next에서 의도한 버전이 보인다.
• Edge Runtime 의존을 제거했거나 전환을 보류한 이유가 기록돼 있다.
• middleware.ts와 예전 named export가 남지 않았다.
• npm run build가 통과한다.
• matcher 대상 경로에서 redirect, rewrite, header가 이전과 같이 동작한다.
• 대상이 아닌 경로에서는 Proxy가 불필요하게 실행되지 않는다.

배포 단계에서만 문제가 난다면 로컬과 배포 결과가 다를 때 빌드 로그를 좁히는 순서로 이어서 확인한다.

Proxy에 인증 전체를 맡기지 않는다

Proxy는 요청을 받기 전의 빠른 경계 판단에 알맞다. 반대로 느린 데이터 조회를 넣거나, 여기서 한 번 redirect했다고 세션과 권한 검사가 끝났다고 보면 안 된다. 공식 문서는 Proxy가 느린 data fetching에 적합하지 않고 완전한 세션 관리나 권한 부여 해법으로 쓰여서는 안 된다고 밝힌다.

따라서 Proxy에서는 cookie 존재 여부 같은 낙관적 확인과 경로 분기를 처리할 수 있지만, 보호된 데이터에 접근하는 서버 코드에서는 권한을 다시 검증해야 한다. 이 경계를 지키기 어렵다면 이름 변경보다 책임 분리가 먼저다.

오늘 할 일은 간단하다. npm ls next와 기존 middleware의 runtime, matcher를 확인한다. 전환 가능 조건이 맞을 때만 codemod를 실행하고, build와 실제 대상 경로가 모두 통과한 결과를 남긴다.

참고 출처

• Proxy (Next.js)
• How to upgrade to version 16 (Next.js)
• Codemods (Next.js)
• Renaming Middleware to Proxy (Next.js)

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.