Миграция мобильного приложения на новую версию Flutter SDK
Мы сталкиваемся с такими проектами каждый месяц. Наш опыт — 5+ лет в Flutter и более 30 успешных миграций — говорит, что переход с Flutter 2.x на 3.x — лишь вершина айсберга. Мы помогаем командам справиться с null safety, новым Navigator 2.0 и изменениями в Material. Миграция производственного приложения — это не просто flutter pub upgrade, а системная работа, которая требует планирования и экспертизы.
Почему миграция Flutter SDK требует профессионального подхода?
Потому что мажорное обновление ломает не только код, но и зависимости, конфигурацию сборки и даже поведение виджетов. С Feature-flag подходом мы сократили время миграции на 30% по сравнению с попыткой обновить всё сразу. Под ключ — с аудитом, исправлением всех breaking changes и тестированием на реальных устройствах.
Что реально ломается при мажорном апгрейде
Null safety: за пределами dart migrate
Инструмент dart migrate делает 70-80% работы — проставляет ? и ! там, где анализатор может вывести nullability. Остальные 20-30% — ручная работа, и именно там скрыты баги.
Типичный случай: плагин из pub.dev не перешёл на null safety и заморожен. Варианты: fork с патчем, замена на альтернативный пакет, написание обёртки. В проекте с 40+ зависимостями это превращается в неделю работы только на зависимости.
Ещё опаснее — код, который проходит миграцию без ошибок, но меняет поведение. late переменная без инициализации бросает LateInitializationError в рантайме там, где раньше был просто null. Ловится только тестами или в продакшене.
Breaking changes в Material 3
Flutter 3.16+ переключил useMaterial3: true по умолчанию. Если в приложении кастомная тема через ThemeData, часть компонентов начинает выглядеть иначе: изменились размеры кнопок, отступы в AppBar, шрифтовая иерархия TextTheme. Приложения, отклонённые из-за внешних изменений после апгрейда — не редкость.
Решение: явно задать useMaterial3: false на время миграции, затем поэтапно переходить на M3 по компоненту.
Изменения в Navigator и роутинге
Если приложение использует go_router, каждый мажорный релиз пакета ломает API по-новому. Переход с go_router 6.x на 10.x — это полный рерайт конфигурации роутов: GoRoute + ShellRoute вместо вложенных GoRoute, изменения в redirect callback сигнатуре, новый StatefulShellRoute для persistent navigation.
Изменения в рендеринге: Impeller
Flutter 3.10+ включил Impeller по умолчанию на iOS (Android — опционально). Impeller убирает jank от компиляции шейдеров, но ломает кастомные CustomPainter реализации, использующие нестандартные BlendMode или ImageFilter. После включения Impeller нужно прогнать все анимации и кастомные виджеты на реальных устройствах.
Как правильно спланировать миграцию Flutter SDK?
Процесс миграции
Аудит зависимостей — первый шаг. flutter pub outdated показывает что устарело, но не показывает breaking changes. Смотрим CHANGELOG каждого пакета из pubspec.yaml вручную для мажорных версий. Зависимости делим на три категории:
- обновляются без изменений кода
- требуют изменений кода (API changes)
- нет совместимой версии — нужна замена или fork
Feature-flag подход для крупных приложений. Создаём migration ветку, обновляем SDK и пакеты, фиксируем все ошибки компиляции. Затем исправляем поэтапно, начиная с core-слоя (модели, репозитории) и заканчивая UI.
Тестирование после миграции:
-
flutter analyze— статический анализ без предупреждений -
flutter test— весь существующий suite должен проходить - Golden tests для UI-компонентов (если используются) нужно перегенерировать — Impeller рендерит пиксели иначе
- Smoke-тест на физических устройствах: iOS + Android, бюджетный Android обязателен
Типичные ошибки при миграции и их решение
| Ошибка | Причина | Решение |
|---|---|---|
LateInitializationError |
late переменная не инициализирована |
Проверить все late поля, добавить проверки или использовать ? |
| Виджеты выглядят иначе | Material 3 включён по умолчанию | Явно задать useMaterial3: false |
go_router не компилируется |
Мажорное изменение API | Переписать конфигурацию роутов под новую версию |
| Плагин несовместим | Нет версии под новую Dart | Fork, замена или обёртка |
Что входит в работу по миграции
- Аудит текущего кода и зависимостей с составлением отчёта
- Обновление SDK и всех пакетов с фиксацией breaking changes
- Исправление кода: null safety, Material 3, Navigator, Impeller
- Написание и обновление тестов (unit, widget, golden)
- Smoke-тесты на физических устройствах iOS и Android
- Помощь в публикации в App Store и Google Play
Чек-лист для самостоятельной миграции
- Выполнить
flutter pub outdated - Прочитать CHANGELOG каждого мажорного пакета
- Зафиксировать все ошибки компиляции
- Исправить core-слой (модели, репозитории)
- Переключить Material 3 в
falseпри необходимости - Обновить golden-тесты
- Протестировать на реальных устройствах
Конкретные проблемы из практики
В проекте (e-commerce, Flutter 2.8 → 3.19) основная трудность была не в коде, а в плагине flutter_local_notifications. Между версиями 9.x и 16.x изменился весь Android-сайд: новый FlutterLocalNotificationsPlugin.initialize() с InitializationSettings, обязательный onDidReceiveNotificationResponse вместо deprecated колбека. Плюс Android 13 требует явного POST_NOTIFICATIONS permission — без него тихо не работает.
Другой случай — image_picker после обновления начал возвращать XFile вместо File. Везде в коде File(imagePicker.path) заменяли на File(xFile.path) — механически, но их было 23 использования в разных экранах.
Сроки
| Масштаб приложения | Типичный срок миграции |
|---|---|
| Small (< 20 экранов, < 15 зависимостей) | 3-5 дней |
| Medium (20-60 экранов, 15-40 зависимостей) | 1-3 недели |
| Large (60+ экранов, сложная архитектура) | 3-6 недель |
Стоимость рассчитывается индивидуально после аудита репозитория и списка зависимостей. Получите консультацию — мы оценим ваш проект и предложим сроки.
Подробнее о breaking changes читайте в официальном руководстве Flutter.