Nextjs 미들웨어에 대해서

 

리프레시 토큰 재발급 작업을 진행하면서, Next.js 미들웨어에 대해 좀 더 깊게 공부를 하게 되어 정리할 겸 9월 포스팅 👀

사실 .. 이 작업은 7월에 해서 .. 7월에 작성해둔 글인데 이제서야 올려요 ㅎ

 

 

미들웨어를 활용하면 Request 단계에서 인증/인가를 처리하거나, 특정 경로로 리다이렉트하는 작업을 손쉽게 구현할 수 있음!

 

1. 미들웨어 실행 범위

• 페이지 요청 
• API 요청
  •  클라이언트가 API를 호출하면 Next.js 서버에 요청이 도착하기 전에 미들웨어가 먼저 실행됨 (여기서 인증 토큰 검사, IP 필터링, 로깅 등을 수행할 수 있음.)
  • 서버 코드에서 내부 API를 호출할 때도 미들웨어가 동작
    • (단, 서버 내부 요청은 브라우저 컨텍스트가 아니므로 쿠키가 자동으로 넘어가지 않음 -> 필요한 경우 headers에 토큰을 붙여서 전달)
• 정적 파일 (/public/* 같은 자원 -> matcher로 지정 가능)
• 클라이언트 사이드 네비게이션 (Link, router.push)
  • 내부적으로 서버 요청이 발생하므로 미들웨어가 동작

* 정리

 

• 페이지 리로드 (브라우저 새로고침, 직접 URL 입력, 새 창 열기 등)
  → 서버로 새로운 요청 발생하므로 미들웨어 실행
• 클라이언트 사이드 네비게이션 (next/link, router.push)
  → 내부적으로 페이지 데이터(JSON/HTML) 요청 발생하므로, 미들웨어 실행
• CSR에서만 발생하는 상태 변경 (예: useState로 UI만 변경)
  → 서버로 요청 없으므로, 미들웨어 실행 안 됨
• 정적 빌드된 HTML이 캐싱된 경우
  (예: output: 'export'로 정적 내보내기)
  → 서버/엣지 요청 자체가 없으므로, 미들웨어 실행 안 됨

 

 

2.  미들웨어 특징

- 미들웨어는 기본적으로 모든 요청에 실행됨.

 

- config.matcher를 통해 필요한 경로만 지정할 수도 있음.

      -> 이유 : 기본값은 *라서 모든 경로가 실행되기 때문에 성능 저하 가능성 ..

// 특정 경로에만 미들웨어 적용
export const config = {
  matcher: ['/dashboard/:path*', '/api/secure/:path*'],
};

 

- 대규모 데이터 처리나 무거운 암호화 같은 CPU 집약적인 연산은 여기서 처리하지 않는 것이 좋음.

 

 

3. 미들웨어 동작 방식

1. 클라이언트가 요청을 보냄. (페이지 접근 또는 API 호출)
2. 요청이 Next.js 서버로 전달되기 전에 미들웨어가 실행.
   • 이 단계에서 요청을 수정하거나 다른 경로로 리다이렉트.
   • 토큰 검사, 필요 시 리다이렉트
3. 서버가 요청을 처리하고 응답을 생성. (API 응답 생성 / 페이지 렌더링)
4. 최종적으로 클라이언트에 응답이 전달.

 

 

참고: Next.js 미들웨어는 Request 시점에서만 실행됨.
Response를 직접 가로채진 않지만, 요청을 변형하거나 리다이렉트하여 결과적으로 응답에 영향을 줄 수 있음.