Vue Router 3 vs 4 비교: Vue2에서 Vue3로 라우터 마이그레이션

Vue Router 기초와 Vue Router 3가 궁금하다면?

2025.11.19 - [Web/Vue] - Vue Router 기초 (Vue 2 + Vue Router 3)

Vue Router 기초 (Vue 2 + Vue Router 3)

 

 

1. 왜 Vue Router 4를 공부해야 할까?

실무에서는 Vue 2 기반 레거시 프로젝트를 유지하면서

새 기능이나 신규 서비스는 Vue 3 기준으로 올려야 하는 경우가 많습니다.

그래서 Router 3만 따로, Router 4만 따로 보는 것보다

같은 기능이 Router 3에서는 이렇게, Router 4에서는 저렇게라는 식으로 비교해두면

나중에 실제 코드를 바꿀 때 훨씬 덜 헤매게 됩니다.

 

---

 

2. 버전 정리

• Vue 2 ↔ Vue Router 3.X
• Vue 3 ↔ Vue Router 4.X

공식 문서에서도 Vue 3에서는 Router 4를 사용하라고 명시하고 있고,

Router 4는 createRouter, createWebHistory 같은 새 API를 중심으로 설계되어 있습니다.

즉, Vue 3 프로젝트를 하면서 Router 3를 쓰는 일은 없다고 생각해도 됩니다.

 

---

 

3. 앱에 라우터를 등록하는 방식 비교

Vue 2 + Router 3

// main.js
import Vue from 'vue'
import App from './App.vue'
import router from './router'

new Vue({
	router,
    render: h => h(App)
}).$mount('#app')

// router/index.js
import Vue from 'vue'
import Router from 'vue-router'
import Home from '@/views/Home.vue'
import About from '@/views/About.vue'

Vue.use(Router)

export default new Router({
	modes: 'history',
    routes: [
    	{ path: '/', name: 'home', component: Home },
        { path: '/about', name: 'about', component: About }
    ]
})

• 전역 Vue 생성자 + Vue.use(Router)
• new Router({ ... })
• mode: 'history'/'hash'로 모드 지정

 

---

 

Vue 3 + Router 4

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
app.use(router)
app.mount('#app')

// router/index.js
import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '@/views/HomeView.vue'
import AboutView from '@/views/AboutView.vue'

const routes = [
	{ path: '/', name: 'home', component: HomeView },
    { path: '/about', name: 'about', component: AboutView }
]

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

export default router

• 전역 Vue.use() 대신 웹 인스턴스에 app.use(router)
• new Router() 대신 createRouter()
• mode: 'history' 대신 history: createWebHistory()를 사용

 

---

 

마이그레이션 포인트

• Vue.use(Router) 제거
• new Router({ mode }) → createRouter({ history })
• main.js에서 router, render 옵션 대신 createApp().use(router).mount() 패턴으로 변경

 

---

 

4. <router-view>와 <router-link>는 거의 그대로

템플릿 쪽은 크게 바뀌지 않습니다.

Vue 2 + Router 3와 Vue 3 + Router 4 모두 아래와 같이 사용할 수 있습니다.

<template>
	<div>
    	<nav>
        	<router-link to="/">Home</router-link>
            <router-link to="/about">About</router-link>
        </nav>
        <router-view />
    </div>
</template>

• <router-view>: 현재 라우트에 맞는 컴포넌트가 렌더되는 자리
• <router-link>: 새로고침 없이 라우터를 통해 화면 전환하는 링크

 

Router 4에서는 <RouterView>, <RouterLink>처럼 PascalCase도 지원합니다.

<script>
import { RouterLink, RouterView } from "vue-router"
</script>

<template>
	<div>
    	<nav>
        	<RouterLink to="/">Home</RouterLink>
            <RouterLink to="/about">About</RouterLink>
        </nav>
        <RouterView />
    </div>
</template>

 

하지만 기존 <router-view>, <router-link> 방식 그대로 써도 동작합니다.

바뀐 것은 주로 JS 쪽 설정(main.js, router/index.js)입니다.

 

---

 

5. 동적 라우트 사용방법

한 줄로 요약하자면, 개념은 그대로인데 훅만 달라졌습니다.

 

Vue 2 + Router 3

// router/index.js
export default new Router({
	mode: 'history',
    routes: [
    	{ path: '/posts/:id', name: 'post-detail', component: PostDetail }
    ]
})

 

---

 

Vue 3 + Router 4

라우트 정의는 거의 똑같습니다.

// router/index.js
const routes = [
    { path: '/posts/:id', name: 'post-detail', component: PostDetailView }
]

차이는 컴포넌트에서 라우트에 접근하는 방식입니다.

---

 

1) Options API 그대로 쓸 경우

<script>
export default {
	created() {
    	console.log('id:', this.$route.params.id)
    }
}
</script>

Vue 3에서도 $route, $router는 여전히 쓸 수 있습니다.

 

---

 

2) Composition API 사용할 경우 (권장 패턴)

<script setup>
import { useRoute } from 'vue-router'

const route = useRoute()
const id = route.params.id
</script>

<template>
	<div>Post ID: {{ id }}</div>
</template>

• Rotuer 4에서는 useRoute, useRouter 훅을 제공
• Composition API와 함게 쓰기 좋게 설계되어 있습니다.

 

---

 

마이그레이션 포인트

• 기존 $route, $router 기반 로직은 Composition API로 옮길 때 useRouter, useRouter로 치환
• Options API 그대로 유지한다면 $route를 계속 써도 동작은 함 (단, 점진적으로 훅 기반으로 옮겨가는 걸 추천)

 

---

 

6. 네비게이션 가드 패턴 간단 비교

상세 가드는 나중에 따로 따도 되니, 여기서는 마이그레이션 감각만 잡아보겠습니다.

 

Vue 2 + Router 3

const router = new Router({ ... })

router.beforeEach((to, from, next) => {
	if (to.meta.requiresAuth && !isLoggedIn()) {
    	next('/login')
    } else {
    	next()
    }
})

 

---

 

Vue 3 + Router 4

const router = createRouter({ ... })

router.beforeEach((to, from) => {
	if (to.meta.requiresAuth && !isLoggedIn()) {
    	return { path: '/login' }
    }
})

Router 4에서는 next() 콜백 대신 아래처럼 값을 리턴하는 패턴을 더 권장합니다.

• return false → 내비게이션 취소
• return { path: '/login' } → 다른 경로로 리다이렉트

기존 next()도 사용할 수 있지만, 공식 문서에서는 리턴 기반 패턴을 보여줍니다.

 

---

 

마이그레이션 포인트

• Router 3의 next() 기반 가드를 그대로 써도 동작하긴 함
• Router 4 스타일로 정리하려면  return 기반으로 차차 리팩토링

 

---

 

7. 변경점 요약

Router 3에서 Router 4로 넘어갈 때 코드레벨에서 체감되는 변화를 정리해보겠습니다.

1. 생성 방식
   • new Router({ mode }) → createRouter({ history })
2. 앱 등록 방식
   • Vue.use(Router) → 제거
   • new Vue({ router }) → createApp(App).use(router).mount()
3. Composition API 공식 지원
   • $route, $router 외에 useRoute, useRouter 훅 사용
4. 네비게이션 가드 리턴 패턴
   • next() 콜백 → 값 리턴 패턴으로 점진적 전환

이 네가지만 정확히 잡고 있으면, 기존 Vue 2 / Router 3 글을 참고하면서 Router 4와 대응시키기 좋습니다.

 

---

 

출처

Vue Router 4 공식 문서 - 소개

Vue Router 4 공식 문서 - 설치

Vue Router 4 공식 문서 - 시작하기

Vue Router 4 공식 문서 - 컴포지션 API

Vue Router 4 공식 문서 - Vue 2에서 마이그레이션