[Nuxt3] 라우트 미들웨어

 

미들웨어는 Nuxt에서 특정 페이지를 렌더링하기 전에 실행되는 함수로, 주로 사용자 인증, 접근 제한, 데이터 로딩, 리디렉션 처리 등의 작업을 수행하는 데 사용된다.

 

Nuxt 미들웨어의 종류 및 실행 시점

Nuxt에서는 미들웨어를 적용하는 방식에 따라 크게 세 가지 종류로 나눌 수 있다.

미들웨어 종류	적용 방법	실행 시점
글로벌 미들웨어 (Global Middleware)	nuxt.config.ts에서 설정	모든 페이지 접근 시 실행
라우트 미들웨어 (Route Middleware)	definePageMeta({ middleware })를 사용하여 페이지에 지정	특정 페이지 접근 시 실행
컴포넌트 단위 미들웨어 (Component Middleware)	onBeforeMount 또는 useAsyncData 활용	특정 컴포넌트가 마운트될 때 실행

 

미들웨어 자동 등록 동작 방식

Nuxt는 middleware/ 디렉터리에 있는 모든 파일을 자동으로 감지한다. 따라서, 글로벌 미들웨어든 라우트 미들웨어든 별도 설정 없이 바로 적용 가능하다. 반면, 라우트 미들웨어는 자동으로 등록되지 않으며, 명시적으로 설정해야 한다. 즉, definePageMeta({ middleware })를 통해 선언해야 실행된다.

미들웨어	유형등록 방식	실행 시점	nuxt.config.ts 설정 필요 여부
글로벌 미들웨어	middleware/*.global.ts	모든 라우트	❌ 필요 없음 (자동 등록)
라우트 미들웨어	middleware/*.ts + definePageMeta({ middleware })	특정 라우트	⭕ 필요 (페이지에서 명시적으로 선언)
컴포넌트 미들웨어	onBeforeMount(), useAsyncData() 등	특정 컴포넌트	❌ 필요 없음

 

 라우트 미들웨어 실행 시점 및 주의점

🚨 Nuxt에서는 사이트가 서버 렌더링되거나 정적 사이트로 생성될 경우, 초기 페이지의 미들웨어는 서버에서 실행되고 이후 클라이언트에서 다시 실행된다. 즉, 하나의 미들웨어가 SSR(서버) → CSR(클라이언트) 두 번 실행될 수 있다. 이는 브라우저 환경을 필요로 하는 로직(예: localStorage, window 객체 사용)이 있을 경우 문제가 될 수 있다.

✅ SSR에서 미들웨어 실행을 막는 방법

// middleware/example.ts
export default defineNuxtRouteMiddleware((to) => {
  // 서버에서 실행되는 것을 방지
  if (process.server) return;
  
  // 클라이언트에서 실행되더라도 전체 미들웨어 건너뛰기
  if (process.client) return;

  // 초기 클라이언트 로드에서만 미들웨어 건너뛰기 (Hydration 시점에는 실행하지 않도록 처리)
  const nuxtApp = useNuxtApp();
  if (process.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) return;
});

이 방법을 사용하면 로컬 스토리지 접근, 브라우저 API 호출 등의 오류를 예방할 수 있다.

라우트 미들웨어 실행 순서

Nuxt에서 라우트 미들웨어는 다음 순서대로 실행된다.

글로벌 미들웨어 (Global Middleware)

• middleware/*.ts 에 정의된 글로벌 미들웨어가 알파벳 순서대로 실행됨.
• nuxt.config.ts에서 등록하여 모든 라우트에 적용됨.

라우트 미들웨어 (Route Middleware)

• definePageMeta({ middleware }) 에서 선언된 미들웨어가 정의된 순서대로 실행됨.
• 배열 형태로 여러 개 선언할 경우, 선언된 순서대로 실행됨.

컴포넌트 단위 미들웨어 (Component Middleware)

• 특정 Vue 컴포넌트 내에서 onBeforeMount, useAsyncData 등으로 실행됨.
• 일반적으로 라우트 미들웨어가 실행된 후 실행됨.

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  console.log("✅ Auth 미들웨어 실행됨:", to.fullPath);
});

// middleware/logger.ts
export default defineNuxtRouteMiddleware((to) => {
  console.log("✅ Logger 미들웨어 실행됨:", to.fullPath);
});

<script setup>
definePageMeta({
  middleware: ["logger", "auth"], // 실행 순서: logger → auth
});
</script>

✅ 실행 순서

1. Global Middleware (알파벳 순서)
2. Route Middleware (logger → auth 순서대로 실행)
3. 컴포넌트 내 onBeforeMount 실행