Migration Build использование

Migration Build — специальная сборка Vue.js, предназначенная для упрощения процесса перехода с Vue 2 на Vue 3. Она сочетает в себе возможности Vue 3 и поддержку устаревших API, что позволяет постепенно обновлять кодовую базу без необходимости полной переработки приложения.

Основные цели Migration Build

  1. Совместимость с устаревшими API Migration Build включает механизмы, которые позволяют старым функциям Vue 2 работать в Vue 3. Это особенно полезно для крупных приложений, где миграция всей кодовой базы за один шаг невозможна.

  2. Выявление проблем совместимости При использовании Migration Build приложение выводит предупреждения о deprecated API и потенциально несовместимых конструкциях. Это помогает выявлять и исправлять устаревший код по мере работы с проектом.

  3. Пошаговая миграция Migration Build позволяет применять новую архитектуру Vue 3 постепенно, модуль за модулем, без полной остановки проекта.

Подключение Migration Build

Migration Build можно подключить через CDN или пакет npm. Для npm используется специальный пакет:

npm install @vue/compat

В проекте с Vite или Webpack импорт осуществляется следующим образом:

import { createApp } from 'vue/compat'
import App from './App.vue'

createApp(App).mount('#app')

Важно убедиться, что сборка проекта использует vue/compat, а не стандартный vue.

Отличия от стандартной сборки Vue 3

Особенность Стандартная Vue 3 Vue 3 Migration Build
Поддержка Vue 2 API Нет Да
Вывод предупреждений о deprecated API Нет Да
Совместимость с Vue 2 плагинами Ограничена Поддерживается частично
Размер сборки Меньше Чуть больше из-за дополнительных проверок

Конфигурация предупреждений

Migration Build позволяет управлять предупреждениями, чтобы разработчик видел только актуальные проблемы:

import { configureCompat } from 'vue/compat'

configureCompat({
  MODE: 2, // Активирует Vue 2 совместимость
  // Настройка предупреждений
  GLOBAL_MOUNT: 'warn', 
  GLOBAL_EXTEND: 'error',
  OPTION_DATA_FN: 'warn'
})
  • MODE: 2 — включает режим совместимости с Vue 2.
  • GLOBAL_MOUNT и другие параметры задают реакцию системы: warn, error или silent.

Такой подход позволяет гибко управлять процессом миграции и постепенно исправлять устаревший код.

Использование устаревших опций

Migration Build поддерживает большинство API Vue 2, таких как:

  • filters
  • inline-template
  • v-on.native
  • keyCode модификаторы

При этом Vue 3 рекомендует постепенно заменять их на Composition API, computed свойства и глобальные методы.

Пример фильтра, работающего в Migration Build:

Vue.filter('uppercase', function (value) {
  if (!value) return ''
  return value.toUpperCase()
})

Такой фильтр будет работать, но одновременно в консоли появится предупреждение о том, что filters устарели.

Работа с плагинами и сторонними библиотеками

Некоторые плагины Vue 2 могут требовать адаптации при использовании Migration Build:

  • Проверяется наличие deprecated API, используемого плагином.
  • Для Vuex и Vue Router версии 3 рекомендуется использовать совместимые версии или обновленные модули.
  • Плагины, полностью переписанные для Vue 3, могут работать без изменений.

Ограничения Migration Build

  1. Не гарантирует полную совместимость — некоторые плагины и глубоко интегрированные решения могут требовать ручного исправления.
  2. Увеличение размера сборки — из-за включения поддержки старого API.
  3. Временное решение — Migration Build не предназначен для долгосрочной эксплуатации, основной целью является постепенный переход на чистый Vue 3.

Практический сценарий использования

  1. Подключение vue/compat в существующем проекте Vue 2.
  2. Настройка configureCompat для контроля предупреждений.
  3. Постепенная замена устаревших опций на Composition API или современные директивы.
  4. Проверка совместимости плагинов и сторонних библиотек.
  5. Пошаговый переход к стандартной сборке Vue 3 после устранения всех deprecated API.

Migration Build обеспечивает мост между двумя поколениями Vue, позволяя обновлять приложения без полной переработки и минимизируя риск поломки функционала. Он особенно полезен для крупных корпоративных проектов и постепенно модернизируемых кодовых баз.

Оглавление