Next.js middleware.ts가 배포 후 조용히 안 먹힌 이유

문제 발생

Next.js를 최신 버전으로 올린 뒤, 기존에 잘 동작하던 인증 리다이렉트 로직(middleware.ts)이 배포 후 더 이상 실행되지 않는 것처럼 보였습니다.

원인 분석

Next.js는 middleware.ts를 deprecated하고 proxy.ts(export default function proxy(...))로 이름을 바꿨습니다. 파일이 여전히 middleware.ts로 남아 있으면, 버전에 따라 경고만 뜨고 동작은 하거나, 완전히 인식되지 않는 상태가 될 수 있습니다 — 정확한 동작은 실제 설치된 Next.js 버전의 마이그레이션 가이드를 확인해야 합니다.

단순히 파일명만 바꾼다고 끝나는 것도 아닙니다. 실제로 자주 놓치는 것은 다음과 같습니다.

1. matcher 설정 누락: 파일을 옮기면서 기존 config.matcher 배열을 그대로 옮기지 않으면, 원래 보호하려던 라우트가 더 이상 이 로직을 거치지 않게 됩니다.
2. request.url/request.nextUrl을 신뢰하는 문제: 로컬 개발 서버가 이 값을 서버 바인드 주소로 정규화하는 경우가 있어, 실제 요청 Host와 다르게 나올 수 있습니다. 리다이렉트 목적지를 만들 때 raw Host 헤더 기반의 별도 유틸리티를 쓰는 것이 안전합니다.
3. 이건 인가(authorization)가 아니라는 점: middleware/proxy는 페이지가 실제로 렌더링되기 전의 최적화된 리다이렉트 계층이지, 진짜 권한 검증 계층이 아닙니다. 여기서만 인증을 확인하고 페이지 자체에서 세션을 다시 검증하지 않으면, matcher 설정 실수나 라우트 이동 한 번으로 보호가 조용히 빠질 수 있습니다.

해결 방안

1. middleware.ts를 proxy.ts로 옮기고 export default function middleware를 export default function proxy로 바꿉니다.
2. config.matcher 배열이 원래 보호하려던 모든 경로를 그대로 포함하는지 하나씩 확인합니다.
3. proxy/middleware의 리다이렉트는 UX 최적화로만 취급하고, 실제 인가는 보호 대상 페이지 자신이 세션을 다시 검증하도록 이중으로 구현합니다.
4. 로컬 개발에서 커스텀 도메인(서브도메인 등)을 쓴다면 next.config.ts의 allowedDevOrigins 설정이 필요한지도 함께 확인합니다.

공식 문서

• Next.js Docs: proxy.ts

이 영역은 Next.js 메이저 버전마다 API가 바뀌는 경우가 많으므로 반드시 현재 설치된 버전의 공식 문서를 우선 확인합니다.