Vue Routerの使い方を基礎から実践まで体系的に解説【Vue 3対応】

# npm
npm install vue-router@4

# yarn
yarn add vue-router@4

# pnpm
pnpm add vue-router@4

// src/router/index.ts
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(import.meta.env.BASE_URL),
  routes,
})

export default router

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

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

<!-- src/App.vue -->
<script setup lang="ts">
import { RouterLink, RouterView } from 'vue-router'
</script>

<template>
  <nav>
    <RouterLink to="/">ホーム</RouterLink>
    <RouterLink to="/about">概要</RouterLink>
  </nav>
  <RouterView />
</template>

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

const routes = [
  {
    path: '/users/:id',
    name: 'user-detail',
    component: UserDetail,
  },
  {
    path: '/posts/:year/:slug',
    name: 'post',
    component: PostView,
  },
]

const routes = [
  {
    path: '/dashboard',
    component: DashboardLayout,
    children: [
      { path: '', name: 'dashboard-home', component: DashboardHome },
      { path: 'settings', name: 'dashboard-settings', component: DashboardSettings },
      { path: 'profile', name: 'dashboard-profile', component: DashboardProfile },
    ],
  },
]

<!-- DashboardLayout.vue -->
<template>
  <div class="dashboard">
    <aside>サイドバー</aside>
    <main>
      <RouterView />
    </main>
  </div>
</template>

<RouterLink :to="{ name: 'user-detail', params: { id: 42 } }">
  ユーザー詳細
</RouterLink>

<template>
  <!-- 文字列パス -->
  <RouterLink to="/about">概要ページ</RouterLink>

  <!-- オブジェクト形式 -->
  <RouterLink :to="{ name: 'user-detail', params: { id: userId } }">
    プロフィール
  </RouterLink>

  <!-- クエリ付き -->
  <RouterLink :to="{ path: '/search', query: { q: 'vue' } }">
    検索
  </RouterLink>
</template>

<script setup lang="ts">
import { useRouter } from 'vue-router'

const router = useRouter()

function goToUser(id: number) {
  router.push({ name: 'user-detail', params: { id } })
}

function searchKeyword(keyword: string) {
  router.push({ path: '/search', query: { q: keyword } })
}
</script>

// 方法1
router.replace({ path: '/home' })

// 方法2（pushのオプションとして指定）
router.push({ path: '/home', replace: true })

router.go(-1)  // 1つ前に戻る
router.go(1)   // 1つ先に進む

<script setup lang="ts">
import { useRoute } from 'vue-router'

const route = useRoute()

// /users/42 の場合
console.log(route.params.id) // '42'

// /search?q=vue&page=2 の場合
console.log(route.query.q)    // 'vue'
console.log(route.query.page) // '2'
</script>

// ルート定義
{
  path: '/users/:id',
  name: 'user-detail',
  component: UserDetail,
  props: true, // route.params をそのまま props として渡す
}

<!-- UserDetail.vue -->
<script setup lang="ts">
const props = defineProps<{
  id: string
}>()
</script>

<template>
  <div>ユーザーID: {{ id }}</div>
</template>

// src/router/index.ts
router.beforeEach((to, from) => {
  const isAuthenticated = !!localStorage.getItem('token')

  if (to.meta.requiresAuth && !isAuthenticated) {
    return { name: 'login', query: { redirect: to.fullPath } }
  }
})

const routes = [
  {
    path: '/mypage',
    name: 'mypage',
    component: MyPage,
    meta: { requiresAuth: true },
  },
  {
    path: '/login',
    name: 'login',
    component: LoginView,
  },
]

router.beforeResolve(async (to) => {
  if (to.meta.requiresPermission) {
    try {
      await checkPermission(to.meta.requiredRole as string)
    } catch {
      return { name: 'forbidden' }
    }
  }
})

const routes = [
  {
    path: '/admin',
    component: AdminPanel,
    beforeEnter: (to, from) => {
      const userRole = getUserRole()
      if (userRole !== 'admin') {
        return { name: 'home' }
      }
    },
  },
]

function validateId(to) {
  if (isNaN(Number(to.params.id))) return { name: 'not-found' }
}
function logAccess(to) {
  console.log(`Accessed: ${to.fullPath}`)
}

const routes = [
  {
    path: '/items/:id',
    component: ItemDetail,
    beforeEnter: [validateId, logAccess],
  },
]

<script setup lang="ts">
import { ref } from 'vue'
import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router'

const hasUnsavedChanges = ref(false)

// 同じルートでパラメータが変わった時
onBeforeRouteUpdate((to, from) => {
  console.log(`パラメータ変更: ${from.params.id} → ${to.params.id}`)
})

// ページから離れる時
onBeforeRouteLeave((to, from) => {
  if (hasUnsavedChanges.value) {
    const confirmed = window.confirm('未保存の変更があります。離れますか？')
    if (!confirmed) return false
  }
})
</script>

// src/router/middleware/auth.ts
export function authMiddleware(to, from) {
  if (!localStorage.getItem('token')) {
    return { name: 'login', query: { redirect: to.fullPath } }
  }
}

// src/router/middleware/role.ts
export function roleMiddleware(requiredRole: string) {
  return (to, from) => {
    const userRole = getUserRole()
    if (userRole !== requiredRole) {
      return { name: 'forbidden' }
    }
  }
}

// src/router/index.ts
import { authMiddleware } from './middleware/auth'
import { roleMiddleware } from './middleware/role'

const routes = [
  {
    path: '/admin/users',
    component: AdminUsers,
    beforeEnter: [authMiddleware, roleMiddleware('admin')],
  },
]

import { createWebHistory } from 'vue-router'

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

location / {
  try_files $uri $uri/ /index.html;
}

import { createWebHashHistory } from 'vue-router'

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

import { createMemoryHistory } from 'vue-router'

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

// 静的インポート（初回にすべてバンドルされる）
// import UserList from '../views/UserList.vue'

// 動的インポート（アクセス時にロードされる）
const UserList = () => import('../views/UserList.vue')

const routes = [
  {
    path: '/users',
    name: 'user-list',
    component: UserList,
  },
  {
    path: '/settings',
    name: 'settings',
    // ルート定義内に直接記述も可能
    component: () => import('../views/SettingsView.vue'),
  },
]

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'admin-group': [
            './src/views/AdminDashboard.vue',
            './src/views/AdminUsers.vue',
            './src/views/AdminSettings.vue',
          ],
        },
      },
    },
  },
})

import type { RouteRecordRaw } from 'vue-router'

const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'home',
    component: () => import('../views/HomeView.vue'),
  },
  {
    path: '/users/:id',
    name: 'user-detail',
    component: () => import('../views/UserDetail.vue'),
    props: true,
  },
]

<script setup lang="ts">
import { useRoute, useRouter } from 'vue-router'

const router = useRouter()  // Router 型
const route = useRoute()    // RouteLocationNormalizedLoaded 型

// route.params.id は string | string[] 型
const userId = route.params.id as string
</script>

// src/router/types.ts
declare module 'vue-router' {
  interface RouteMeta {
    requiresAuth?: boolean
    requiredRole?: string
    title?: string
  }
}

const router = createRouter({
  history: createWebHistory(),
  routes,
  scrollBehavior(to, from, savedPosition) {
    // ブラウザの戻る・進むボタンの場合は前回位置を復元
    if (savedPosition) {
      return savedPosition
    }

    // ハッシュ付きURLの場合はその要素までスクロール
    if (to.hash) {
      return {
        el: to.hash,
        behavior: 'smooth',
      }
    }

    // それ以外はページ先頭にスクロール
    return { top: 0 }
  },
})

// エラーが発生するケース
router.push({ name: 'search', query: { q: 'vue' } })
// 同じクエリで再度pushすると NavigationDuplicated

// 対処法1: catchで無視する
router.push({ name: 'search', query: { q: 'vue' } }).catch(() => {})

// 対処法2: 遷移前にルートを比較する
function safeNavigate(to: RouteLocationRaw) {
  const resolved = router.resolve(to)
  if (resolved.fullPath !== route.fullPath) {
    router.push(to)
  }
}

const routes = [
  // 他のルート定義...

  // キャッチオールルート（必ず最後に配置）
  {
    path: '/:pathMatch(.*)*',
    name: 'not-found',
    component: () => import('../views/NotFound.vue'),
  },
]

src/pages/
├── index.vue          → /
├── about.vue          → /about
├── users/
│   ├── index.vue      → /users
│   └── [id].vue       → /users/:id
└── [...path].vue      → /:path(.*)* (404)