Next.js middleware matcher 범위를 좁게 설정해야 하는 이유

Next.js에서 middleware를 사용할 때, 어떤 경로에 middleware를 적용할지 정하는 matcher 설정이 중요하다. matcher가 너무 넓으면 모든 요청이 middleware를 거쳐서 성능이 떨어지고, 예상 밖의 부작용이 생긴다.

특히 정적 리소스(이미지, CSS, JS)까지 middleware를 거치게 되면 불필요한 오버헤드가 커진다.

matcher 설정의 기본

middleware.ts 또는 middleware.js에서 matcher를 정의한다.

export const config = {
  matcher: [
    // 이렇게 하면 모든 경로가 middleware를 거침 - 위험
    // '/:path*',

    // 더 안전한 설정: API와 동적 페이지만
    '/api/:path*',
    '/dashboard/:path*',
    '/admin/:path*',
  ]
};

기본값의 문제점

matcher를 설정하지 않으면 Next.js는 기본적으로 특정 정적 파일들을 제외한 모든 경로를 middleware가 처리한다. 하지만 이 기본 제외 목록도 완벽하지 않다.

정적 파일 명시적으로 제외

이미지, 스타일시트, 폰트 등의 정적 파일은 middleware를 거칠 필요가 없다.

export const config = {
  matcher: [
    // 동적 콘텐츠와 API만
    '/((?!_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)',
  ]
};

부정 lookahead((?!...))를 사용해서 제외할 경로를 명시하는 게 더 명확하다.

성능 측정

middleware 범위를 좁힌 후 성능이 개선되는지 확인한다.

# 페이지 로드 시간 측정
time curl -s https://example.com/page

# 또는 lighthouse로 성능 점수 확인
npm run lighthouse

실수하기 쉬운 부분

1. middleware.ts는 프로젝트 루트에만 인식된다 (src/ 폴더 안에 있으면 작동 안 함)
2. matcher 변경 후 npm run dev를 다시 실행해야 적용됨
3. 개발 환경과 프로덕션 빌드에서 동작이 다를 수 있으므로 npm run build로도 확인

로깅으로 어떤 요청이 middleware를 거치는지 확인

export function middleware(request: NextRequest) {
  console.log(`middleware: ${request.nextUrl.pathname}`);
  // ...
}

로그를 보면서 불필요한 요청이 middleware를 거치고 있는지 확인한다.

최종 체크리스트

1. matcher 설정이 정확히 필요한 경로만 포함하는가?
2. 정적 파일은 제외됐는가?
3. npm run build 후에도 정상 동작하는가?
4. 성능 개선이 측정되었는가?

Middleware의 범위를 좁게 설정하는 것은 간단해 보이지만, 성능과 안정성에 직결되는 중요한 작업이다.