Vue Router: руководство по маршрутизации

Крупный план руки, держащей наклейку Vue.js

Vue Router — официальный роутер для Vue, который позволяет создавать одностраничные приложения (SPA). Он помогает сопоставлять компоненты с маршрутами браузера, управлять стеком истории и настраивать сложные паттерны маршрутизации — динамические сегменты, вложенные маршруты, лэйзи-лоадинг и навигационные охранники.

Начало работы с Vue Router

Чтобы создать проект Vue и добавить Vue Router, выполните в терминале команду в папке, где планируете проект:

npm create vue

При создании проекта установщик спросит, добавить ли Vue Router для разработки SPA — выберите “Yes” (Да).

Скриншот выбора Vue Router в подсказке создания проекта

Откройте проект в редакторе. В папке src должен появиться каталог router.

Структура папки router в проекте Vue

В папке router находится index.js (или index.ts при TypeScript) — там создают и экспортируют экземпляр роутера. Обычно в файле импортируют функции createRouter и createWebHistory из пакета vue-router и формируют объект вида { history, routes }.

Пример подключения роутера в main.js:

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

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

После этого Vue-приложение будет использовать маршрутизацию, и вы сможете размещать компоненты-маркеры в шаблонах.

Пример использования в компонентах: импорт RouterLink и RouterView и простая навигация:

Объяснение:

создаёт ссылку на маршрут; атрибут to указывает путь или имя маршрута.
— плейсхолдер, куда Vue будет рендерить компонент текущего маршрута.

Важно: при использовании createWebHistory() сервер должен быть настроен так, чтобы отдавать index.html для всех путей приложения (history mode) — иначе обновление страницы приведёт к 404 на сервере.

Добавление параметров в маршруты

Параметры (params) — динамические части URL, помеченные двоеточием :. В index.js настройте маршрут с параметром:

// index.js
const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: "/",
      name: "home",
      component: HomeView,
    },
    {
      path: "/developer/:profileNumber",
      name: "developer",
      component: () => import("../views/devView.vue"),
    },
  ],
});

В шаблоне можно формировать ссылку с параметром. Пример — в App.vue:

Доступ к параметру внутри компонента devView.vue можно получить двумя способами.

Через глобальный объект $route в шаблоне:

Или через Composition API — импортировать useRoute():

useRoute() возвращает реактивный объект маршрута, поэтому компонент автоматически обновится при смене параметров.

Важно: если ожидаете числовые параметры, приводите их к числу в коде: const id = Number(route.params.profileNumber) и проверяйте валидность.

Добавление query-параметров

Query-параметры идут в URL после ? и имеют формат ключ=значение. Пример: /search?name=vue.

Создать ссылку с query-параметрами можно через объект to:

Home

Доступ к ним также через $route.query или useRoute():

Query-параметры часто используются для фильтрации, пагинации или сохранения состояния поиска. Не храните в query чувствительные данные.

Определение fallback-страницы (404)

Чтобы обработать несуществующие маршруты, добавьте «поймать всё» маршрут в конце массива routes:

{
  path: '/:pathName(.*)',
  name: 'NotFound',
  component: () => import('../views/NotFoundView.vue')
}

Здесь /:pathName(.*) соответствует любому оставшемуся пути. Когда URL не совпадает ни с одним другим маршрутом, отобразится NotFoundView.

Анимации и переходы между маршрутами

Vue предоставляет компонент и для анимации входа и выхода компонентов. Оборачивайте в и задавайте CSS-классы анимации или используйте JavaScript-хуки.

Пример простого перехода:

Переходы делают интерфейс плавнее, но учитывайте производительность при сложных анимациях.

Навигационные охранники и управление доступом

Vue Router поддерживает навигационные охранники (navigation guards): глобальные, на уровне маршрута и на уровне компонента. Они позволяют проверять аутентификацию, загружать данные или отменять навигацию.

Пример глобального охранника в router/index.js:

router.beforeEach((to, from, next) => {
  const requiresAuth = to.meta.requiresAuth;
  const isAuthenticated = /* ваша логика */ false;
  if (requiresAuth && !isAuthenticated) next({ name: 'login' });
  else next();
});

Используйте meta-поле в маршрутах для маркировки страниц с особой логикой (например, requiresAuth).

Important: не храните секреты в meta и всегда проверяйте права на сервере, а не только на клиенте.

Хорошие практики маршрутизации

Храните маршруты централизованно и группируйте их по областям приложения.
Используйте ленивую загрузку (lazy loading) для больших страниц: component: () => import('../views/BigPage.vue').
Валидация параметров: проверяйте Number, регулярные выражения или props в маршрутах.
Избегайте глубоких вложенных маршрутов, если это усложняет структуру компонентов.
Настройте scrollBehavior для плавной прокрутки при навигации:

const router = createRouter({
  history: createWebHistory(),
  routes,
  scrollBehavior(to, from, savedPosition) {
    if (savedPosition) return savedPosition;
    return { top: 0 };
  }
});

Когда Vue Router не подходит

Если приложение — традиционный многостраничный сайт с серверной маршрутизацией (SSR) и вы предпочитаете серверный контроль маршрутов.
Если нужен очень простой сайт без динамики — можно обойтись обычными ссылками и перезагрузками.
Если вы используете фреймворк типа Nuxt (он предоставляет собственную маршрутизацию и абстракции).

Альтернативные подходы

Hash mode (createWebHashHistory) — полезен при хостинге без поддержки history API. URL будет содержать #.
Полная серверная маршрутизация (SPA не используется) — лучше для SEO и простоты бэкенда.
Meta-фреймворки: Nuxt (предоставляет маршруты и SSR), Vite + ручная настройка — в зависимости от требований.

Ментальные модели и эвристики

Маршрут = представление (URL → компонент). Думайте о маршрутах как о ветках приложения.
Params — часть пути (идентификатор сущности). Query — параметры состояния/фильтрации.
RouterView — контейнер, RouterLink — навигация, Router — контроллер маршрутов.

Чек-лист по ролям

Разработчик перед PR:

[ ] Все маршруты описаны в router/index.js.
Используется ленивый импорт для крупных страниц.
Параметры и query валидируются.
Навигационные охранники не блокируют UX без причины.

Ревьюер перед merge:

Наличие тестов на критические маршруты.
Падение на 404 корректно настроено.
Проверены сценарии входа/выхода на страницу с auth.

Шпаргалка (cheat sheet)

Создать роутер: createRouter({ history: createWebHistory(), routes })
Навигация программно: router.push({ name: 'developer', params: { profileNumber: 123 } })
Получить текущий маршрут: const route = useRoute()
Access query: route.query.param
Lazy load: component: () => import('../views/MyView.vue')

Сравнение history vs hash

Особенность	createWebHistory	createWebHashHistory
Чистые URL	Да	Нет (есть #)
Требует серверную настройку	Да	Нет
SEO	Лучше при SSR	Ограничено

Проверка на edge case и рекомендации

Избегайте конфликтов путей: /user/:id и /user/settings — размещайте более конкретные пути раньше или используйте строгие шаблоны.
При динамической подгрузке компонентов проверяйте ошибки импорта и показывайте fallback.
Для пагинации в query используйте числа и валидируйте диапазон.

Безопасность и конфиденциальность

Не храните секреты, токены или персональные данные в URL (params или query).
Валидируйте все входные параметры и экранируйте вывод при необходимости, чтобы избежать XSS.

Мини-методология проектирования маршрутов

Перечислите экраны продукта и их иерархию.
Для каждой сущности определите: нужен ли параметр в пути или query.
Оцените необходимость ленивой загрузки и навигационных охранников.
Настройте 404 и scrollBehavior.
Тестируйте навигацию вручную и автоматизированно (E2E).

Критерии приёмки

Маршруты отображаются корректно при переходе и перезагрузке.
Параметры и query корректно доступны в компонентах.
404 срабатывает для несуществующих URL.
Навигация защищённых страниц работает с учётом авторизации.

Факты и советы

Используйте props: true в настройке маршрута, если хотите передавать params как props в компонент.
Для сложных приложений разделяйте маршруты по модулям (route modules).
Тестируйте как client-side navigation, так и прямой заход по URL.

Краткое резюме

Vue Router — мощный инструмент маршрутизации для Vue-приложений. На старте: создайте проект с опцией Router, подключите роутер в main.js, используйте и . Добавляйте параметры (:id), query (?q=...), ленивую загрузку компонентов, навигационные охранники и fallback 404. Обязательно валидируйте входные параметры и настраивайте сервер при использовании history mode.

Примечание: для сложных сценариев, где важен SSR и SEO, рассмотрите использование Nuxt или другой серверной архитектуры.