Міграція мобільного застосунку на нову версію Flutter SDK
Ми стикаємося з такими проєктами щомісяця. Наш досвід — 5+ років у Flutter та більше 30 успішних міграцій — говорить, що перехід з Flutter 2.x на 3.x — лише вершина айсберга. Ми допомагаємо командам впоратися з null safety, новим Navigator 2.0 та змінами в Material. Міграція виробничого застосунку — це не просто flutter pub upgrade, а системна робота, яка потребує планування та експертизи.
Чому міграція Flutter SDK потребує професійного підходу?
Тому що мажорне оновлення ламає не лише код, а й залежності, конфігурацію збірки та навіть поведінку віджетів. За допомогою Feature-flag підходу ми скоротили час міграції в 1.4 рази порівняно зі спробою оновити все одразу. Під ключ — з аудитом, виправленням усіх 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
- Гарантія на виправлення помилок протягом 30 днів після здачі
Чек-лист для самостійної міграції
- Виконати
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 днів | від $500 |
| Medium (20-60 екранів, 15-40 залежностей) | 1-3 тижні | від $2000 |
| Large (60+ екранів, складна архітектура) | 3-6 тижнів | від $5000 |
Вартість розраховується індивідуально після аудиту репозиторію та списку залежностей. Отримайте консультацію — ми оцінимо ваш проєкт і запропонуємо терміни.
Детальніше про breaking changes читайте в офіційному керівництві Flutter.