FrontendVueTailwind

[Vue 3] Router - 네비게이션 가드

Vue Router의 네비게이션 가드는 라우트 이동 전후에 특정 로직을 실행할 수 있는 훅입니다.

주로 아래 같은 상황에서 사용합니다.

  • 로그인 여부 확인
  • 관리자 페이지 접근 제어
  • 페이지 진입 전 데이터 준비
  • 저장하지 않은 폼 이탈 방지
  • 페이지 이동 로그/분석 처리

기본 예제

// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'
import About from '../views/About.vue'
import Profile from '../views/Profile.vue'

const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home,
  },
  {
    path: '/about',
    name: 'About',
    component: About,
    beforeEnter: (to, from, next) => {
      console.log('About 페이지로 이동 시도')
      next()
    },
  },
  {
    path: '/profile',
    name: 'Profile',
    component: Profile,
    meta: { requiresAuth: true },
  },
]

const router = createRouter({
  history: createWebHistory(),
  routes,
})

router.beforeEach((to, from, next) => {
  const isAuthenticated = localStorage.getItem('token') !== null

  if (to.meta.requiresAuth && !isAuthenticated) {
    next({ name: 'Home' })
  } else {
    console.log(`Navigating from ${from.path} to ${to.path}`)
    next()
  }
})

router.beforeResolve(async (to, from, next) => {
  if (to.meta.requiresData) {
    try {
      console.log('Resolving data for', to.path)
      next()
    } catch (error) {
      next(false)
    }
  } else {
    next()
  }
})

router.afterEach((to, from) => {
  console.log(`Navigation completed to ${to.path}`)
})

export default router

컴포넌트 내부 가드 예제

<!-- views/Profile.vue -->
<template>
  <div>
    <h1>Profile Page</h1>
  </div>
</template>

<script>
export default {
  name: 'Profile',
  beforeRouteEnter(to, from, next) {
    console.log('Entering Profile component')
    next((vm) => {
      vm.loadUserData()
    })
  },
  beforeRouteUpdate(to, from, next) {
    console.log('Updating Profile component')
    next()
  },
  beforeRouteLeave(to, from, next) {
    const confirmLeave = window.confirm('정말 페이지를 나가시겠습니까?')
    if (confirmLeave) {
      next()
    } else {
      next(false)
    }
  },
  methods: {
    loadUserData() {
      console.log('Loading user data')
    },
  },
}
</script>

전역 가드

  • beforeEach: 모든 라우트 이동 전에 실행
  • beforeResolve: 컴포넌트가 렌더링되기 직전에 실행
  • afterEach: 네비게이션 완료 후 실행

라우트별 가드

  • beforeEnter: 특정 라우트에 진입할 때만 실행

컴포넌트 내 가드

  • beforeRouteEnter: 컴포넌트 진입 전
  • beforeRouteUpdate: 같은 컴포넌트가 재사용될 때
  • beforeRouteLeave: 컴포넌트를 떠나기 전

자주 쓰는 사용 사례

  • 인증 상태 체크
  • 비동기 데이터 로딩
  • 페이지 이탈 확인 다이얼로그
  • 페이지 이동 로그 추적
  • 컴포넌트별 데이터 재조회

Vue Router 4에서 달라진 점

Vue Router 4에서는 next() 방식도 사용할 수 있지만, 공식 문서에서는 return 값을 사용하는 방식을 더 권장합니다.

router.beforeEach((to, from) => {
  const isAuthenticated = localStorage.getItem('token') !== null

  if (to.meta.requiresAuth && !isAuthenticated) {
    return { name: 'Login' }
  }
})

가드에서 사용할 수 있는 대표적인 반환값은 아래와 같습니다.

  • undefined: 그대로 통과
  • false: 현재 네비게이션 취소
  • Route Location 객체: 다른 페이지로 리다이렉트
  • throw error: 에러 발생 처리

즉, 기존 코드나 레거시 예제에서는 next()를 많이 보지만, Vue 3 + Vue Router 4 기준에서는 return 패턴도 함께 이해하는 것이 좋습니다.

meta 기반 인증 가드

실무에서는 특정 페이지 이름을 직접 비교하는 것보다 meta.requiresAuth 패턴을 많이 사용합니다.

const routes = [
  {
    path: '/login',
    name: 'Login',
    component: LoginView,
  },
  {
    path: '/profile',
    name: 'Profile',
    component: ProfileView,
    meta: { requiresAuth: true },
  },
]

router.beforeEach((to) => {
  const isAuthenticated = localStorage.getItem('token') !== null

  if (!isAuthenticated && to.meta.requiresAuth && to.name !== 'Login') {
    return { name: 'Login' }
  }
})

장점은 아래와 같습니다.

  • 인증이 필요한 페이지를 라우트 설정에서 바로 확인 가능
  • 전역 가드 재사용이 쉬움
  • 권한 로직이 늘어나도 구조를 유지하기 좋음

beforeEnter 주의점

beforeEnter는 라우트에 “진입”할 때만 실행됩니다.
그래서 같은 라우트에서 params, query, hash만 변경되는 경우에는 다시 실행되지 않습니다.

예를 들면 아래 이동에서는 beforeEnter가 재실행되지 않습니다.

  • /users/1 -> /users/2
  • /users/1?page=1 -> /users/1?page=2
  • /users/1#profile -> /users/1#posts

이런 경우에는 다음 방식을 사용합니다.

  • beforeRouteUpdate
  • watch(() => route.params.id, ...)

네비게이션은 항상 성공하지 않습니다. 아래 상황에서는 이동이 실패할 수 있습니다.

  • 가드에서 false를 반환한 경우
  • 더 새로운 네비게이션이 먼저 시작된 경우
  • 이미 현재 위치와 같은 경로로 이동한 경우

Vue Router는 이를 Navigation Failure로 분류합니다.

  • aborted
  • cancelled
  • duplicated

afterEach는 세 번째 인자로 failure를 받을 수 있습니다.

import { isNavigationFailure, NavigationFailureType } from 'vue-router'

router.afterEach((to, from, failure) => {
  if (!failure) {
    console.log('page view:', to.fullPath)
    return
  }

  if (isNavigationFailure(failure, NavigationFailureType.aborted)) {
    console.log('navigation aborted')
  }
})

이 패턴은 아래 같은 경우에 유용합니다.

  • analytics에서 실제 성공한 page view만 집계
  • 이탈 방지 가드로 인해 취소된 이동 추적
  • 중복 라우팅이나 취소된 이동 디버깅

전체 실행 순서

네비게이션 가드는 아래 순서로 실행됩니다.

  1. beforeRouteLeave
  2. beforeEach
  3. beforeRouteUpdate
  4. beforeEnter
  5. 비동기 라우트 컴포넌트 resolve
  6. beforeRouteEnter
  7. beforeResolve
  8. 네비게이션 확정
  9. afterEach

이 순서를 알고 있으면 가드 충돌이나 데이터 로딩 타이밍 문제를 디버깅하기 쉬워집니다.

정리

네비게이션 가드는 단순히 페이지 이동을 막는 기능이 아니라, 인증, 권한, 데이터 준비, 이탈 방지, 로깅까지 담당하는 라우팅 제어 지점입니다.

특히 Vue Router 4에서는 아래 세 가지를 기억해두면 좋습니다.

  • next()보다 return 방식이 더 현대적인 패턴
  • beforeEnter는 같은 라우트 내부의 params/query/hash 변경에는 다시 실행되지 않음
  • afterEach의 failure를 이용하면 성공/실패한 네비게이션을 구분할 수 있음

참고

Share