به‌روزرسانی Flutter یکی از کارهایی است که توسعه‌دهندگان این فریم‌ورک باید به‌صورت منظم انجام دهند؛ زیرا نسخه‌های جدید معمولاً شامل قابلیت‌های تازه، بهبود عملکرد، رفع باگ، اصلاح مشکلات امنیتی و نسخه‌های جدید Dart SDK هستند.

اما آپدیت Flutter همیشه به معنی اجرای ساده یک دستور نیست. بسته به اینکه Flutter را با Git، Flutter SDK Manager یا روش‌های دیگر نصب کرده باشید، نحوه به‌روزرسانی می‌تواند متفاوت باشد. همچنین بعد از آپدیت ممکن است با خطاهای مربوط به pubspec.lock، پکیج‌ها، Gradle، Android SDK، Xcode یا APIهای Deprecated مواجه شوید.

در این آموزش، روش صحیح آپدیت Flutter به آخرین نسخه، بررسی نسخه فعلی، ارتقای Dart، تغییر Channel، رفع خطاهای رایج و نکات مهم قبل و بعد از Update را بررسی می‌کنیم.

Flutter چیست و چرا باید آن را آپدیت کنیم؟

Flutter یک فریم‌ورک UI متن‌باز برای ساخت اپلیکیشن‌های چندسکویی است که توسط Google توسعه داده شده است.

با Flutter می‌توان برای پلتفرم‌هایی مانند:

• Android
• iOS
• Windows
• macOS
• Linux
• Web

اپلیکیشن توسعه داد.

هر نسخه جدید Flutter معمولاً با تغییرات مختلفی در Flutter Framework، ابزارهای توسعه و Dart SDK همراه است. به همین دلیل، به‌روزرسانی Flutter می‌تواند روی پروژه‌های موجود نیز تأثیر بگذارد.

قبل از آپدیت Flutter نسخه فعلی را بررسی کنید

اولین مرحله این است که ببینید در حال حاضر چه نسخه‌ای از Flutter روی سیستم شما نصب شده است.

ترمینال یا Command Prompt را باز کنید و دستور زیر را اجرا کنید:

flutter --version

برای دریافت اطلاعات کامل‌تر نیز می‌توانید از این دستور استفاده کنید:

flutter doctor -v

خروجی معمولاً اطلاعاتی درباره مواردی مانند:

• Flutter
• Dart
• Android toolchain
• Android Studio
• Xcode
• Connected devices

نمایش می‌دهد.

بهترین روش آپدیت Flutter چیست؟

اگر Flutter را به روش استاندارد نصب کرده باشید، ساده‌ترین روش برای به‌روزرسانی استفاده از دستور زیر است:

flutter upgrade

این دستور Flutter SDK را در Channel فعلی به نسخه جدید موجود ارتقا می‌دهد.

برای مثال اگر روی Stable باشید:

flutter channel stable
flutter upgrade

آموزش آپدیت Flutter به آخرین نسخه

مرحله اول: باز کردن Terminal

در Windows می‌توانید از:

• PowerShell
• Command Prompt
• Terminal داخل VS Code

استفاده کنید.

در macOS و Linux نیز Terminal را باز کنید.

مرحله دوم: بررسی وضعیت Flutter

ابتدا این دستور را اجرا کنید:

flutter doctor

اگر Flutter به‌درستی نصب شده باشد، اطلاعات مربوط به محیط توسعه نمایش داده می‌شود.

سپس نسخه را بررسی کنید:

flutter --version

مرحله سوم: بررسی Channel فعلی

Flutter دارای Channelهای مختلفی است.

برای مشاهده Channel فعلی:

flutter channel

خروجی ممکن است چیزی شبیه این باشد:

Flutter channels:
  master
  main
  dev
  beta
* stable

علامت * نشان می‌دهد که در حال حاضر روی کدام Channel قرار دارید.

Channelهای Flutter چه تفاوتی دارند؟

Flutter چند Channel برای انتشار نسخه‌های مختلف دارد.

Stable

پایدارترین Channel و گزینه پیشنهادی برای اکثر پروژه‌های واقعی است.

flutter channel stable

Beta

نسخه‌هایی که قابلیت‌های جدیدتری نسبت به Stable دارند، اما ممکن است هنوز به اندازه Stable آزمایش نشده باشند.

flutter channel beta

Main

برای توسعه و آزمایش قابلیت‌های جدیدتر Flutter است و برای پروژه‌های Production معمولاً توصیه نمی‌شود.

برای اکثر برنامه‌نویسان، Stable انتخاب مناسب‌تری است.

تغییر Flutter به Stable

اگر به اشتباه روی Channel دیگری قرار دارید و می‌خواهید به Stable برگردید:

flutter channel stable

سپس:

flutter upgrade

بعد نسخه را بررسی کنید:

flutter --version

آپدیت Flutter با یک دستور

اگر Channel شما Stable است، معمولاً کافی است:

flutter upgrade

را اجرا کنید.

پس از پایان فرآیند:

flutter --version

را اجرا کنید تا نسخه جدید را ببینید.

آیا با آپدیت Flutter، Dart هم آپدیت می‌شود؟

بله، Flutter SDK نسخه سازگار Dart SDK را همراه خود دارد.

برای مشاهده نسخه Dart:

dart --version

همچنین:

flutter --version

معمولاً نسخه Flutter و Dart را نمایش می‌دهد.

بنابراین در اکثر موارد، نیازی نیست Dart را جداگانه برای پروژه Flutter به‌روزرسانی کنید.

اگر دستور flutter upgrade کار نکرد چه کنیم؟

اگر با اجرای:

flutter upgrade

خطا دریافت کردید، ابتدا این دستور را اجرا کنید:

flutter doctor -v

سپس مسیر Flutter را بررسی کنید.

در Windows:

where flutter

در macOS و Linux:

which flutter

این دستور نشان می‌دهد سیستم از کدام Flutter SDK استفاده می‌کند.

گاهی چند نسخه Flutter روی سیستم نصب شده و کاربر در حال آپدیت نسخه‌ای غیر از نسخه‌ای است که IDE از آن استفاده می‌کند.

آپدیت Flutter در VS Code

اگر از Visual Studio Code استفاده می‌کنید، بهتر است قبل از آپدیت، Terminal داخلی VS Code را باز کنید.

دستور:

flutter upgrade

را اجرا کنید.

پس از اتمام Update، VS Code را یک‌بار Restart کنید.

همچنین بررسی کنید Extension مربوط به Flutter و Dart نیز به‌روز باشد.

آپدیت Flutter در Android Studio

اگر از Android Studio برای توسعه Flutter استفاده می‌کنید، آپدیت Flutter SDK الزاماً از طریق خود Android Studio انجام نمی‌شود.

می‌توانید Terminal را در Android Studio باز کنید و:

flutter upgrade

را اجرا کنید.

بعد از Update بهتر است Android Studio را Restart کنید.

بعد از آپدیت Flutter چه کارهایی انجام دهیم؟

بعد از ارتقای Flutter، مستقیماً پروژه را Build نکنید.

ابتدا وضعیت محیط را بررسی کنید:

flutter doctor -v

سپس وارد پروژه شوید:

cd my_flutter_project

و این دستور را اجرا کنید:

flutter clean

بعد:

flutter pub get

سپس پروژه را اجرا کنید:

flutter run

چرا بعد از آپدیت باید flutter clean اجرا کنیم؟

گاهی فایل‌های Build و Cache مربوط به نسخه قبلی Flutter با نسخه جدید تداخل پیدا می‌کنند.

اجرای:

flutter clean

فایل‌های Build تولیدشده را پاک می‌کند.

بعد از آن:

flutter pub get

وابستگی‌های پروژه را دوباره دریافت و تنظیم می‌کند.

نکته: flutter clean معمولاً کدهای پروژه یا فایل‌های اصلی شما را حذف نمی‌کند، اما بهتر است قبل از تغییرات اساسی، پروژه را Commit کنید.

آیا بعد از آپدیت باید پکیج‌های Flutter را هم آپدیت کنیم؟

الزاماً نه.

ابتدا پروژه را با همان نسخه‌های فعلی پکیج‌ها اجرا کنید.

برای بررسی پکیج‌های قابل ارتقا:

flutter pub outdated

این دستور اطلاعاتی درباره نسخه فعلی و نسخه‌های جدیدتر Dependencies ارائه می‌کند.

برای ارتقای Dependencies می‌توانید از:

flutter pub upgrade

استفاده کنید.

اما بهتر است آپدیت Flutter و آپدیت تمام پکیج‌های پروژه را هم‌زمان انجام ندهید؛ زیرا اگر خطایی ایجاد شود، تشخیص علت دشوارتر خواهد بود.

تفاوت flutter upgrade و flutter pub upgrade چیست؟

این دو دستور کار متفاوتی دارند.

flutter upgrade

Flutter SDK را ارتقا می‌دهد:

flutter upgrade

flutter pub upgrade

Dependencyهای پروژه Flutter را ارتقا می‌دهد:

flutter pub upgrade

بنابراین:

flutter upgrade
        ↓
Flutter SDK

flutter pub upgrade
        ↓
Project Dependencies

این تفاوت یکی از نکات مهم در مدیریت پروژه‌های Flutter است.

آیا بعد از آپدیت Flutter باید pubspec.yaml را تغییر دهیم؟

نه همیشه.

اگر نسخه Flutter جدید با Dependencyهای فعلی پروژه سازگار باشد، ممکن است هیچ تغییری در pubspec.yaml نیاز نباشد.

اما اگر نسخه جدید Flutter محدودیت‌های جدیدی برای Dart SDK یا یک API ایجاد کرده باشد، ممکن است لازم باشد بخش‌هایی مانند:

environment:
  sdk: "..."

را بررسی کنید.

خطای SDK constraint بعد از آپدیت Flutter

یکی از خطاهای رایج بعد از Update می‌تواند مربوط به SDK Constraint باشد.

برای مثال پروژه ممکن است نسخه قدیمی Dart را در pubspec.yaml مشخص کرده باشد:

environment:
  sdk: ">=2.17.0 <3.0.0"

در حالی که نسخه جدید Flutter از Dart جدیدتری استفاده می‌کند.

در چنین شرایطی باید Compatibility پروژه و پکیج‌ها را بررسی کنید و در صورت نیاز Constraint را به‌روزرسانی کنید.

خطای Deprecated API بعد از آپدیت Flutter

گاهی بعد از آپدیت Flutter، کدی که قبلاً بدون مشکل اجرا می‌شد با Warning یا Error مواجه می‌شود.

دلیل آن می‌تواند حذف یا Deprecated شدن APIهای قدیمی باشد.

برای پیدا کردن مشکلات:

flutter analyze

را اجرا کنید.

این دستور کد پروژه را تحلیل می‌کند و مشکلاتی مانند:

• Deprecated API
• Type Error
• Import مشکل‌دار
• خطاهای Syntax
• مشکلات Null Safety

را گزارش می‌کند.

اگر پروژه بعد از آپدیت اجرا نشد چه کنیم؟

این مراحل را به ترتیب انجام دهید:

flutter clean

سپس:

flutter pub get

بعد:

flutter analyze

و در نهایت:

flutter run

اگر مشکل همچنان وجود داشت، نسخه Flutter و Dart را بررسی کنید:

flutter --version

و:

flutter doctor -v

آپدیت Flutter و مشکل Gradle

یکی از مشکلات رایج در پروژه‌های Android بعد از ارتقای Flutter، ناسازگاری نسخه‌های Android Gradle Plugin، Gradle و Java است.

اگر بعد از Update با خطاهایی مانند:

Gradle build failed

مواجه شدید، باید Compatibility بین این اجزا را بررسی کنید:

Flutter
   ↓
Dart
   ↓
Android Gradle Plugin
   ↓
Gradle
   ↓
Java

در این شرایط نباید صرفاً نسخه Gradle را به‌صورت تصادفی تغییر دهید.

ابتدا متن کامل Error را بررسی کنید و نسخه‌های موردنیاز را بر اساس مستندات همان نسخه Flutter تنظیم کنید.

آپدیت Flutter و مشکل Java

نسخه‌های جدیدتر ابزارهای Android ممکن است به نسخه مشخصی از Java نیاز داشته باشند.

برای بررسی Java:

java -version

اگر Flutter یا Gradle نسخه Java موردنیاز را پیدا نکند، ممکن است Build پروژه با خطا مواجه شود.

به همین دلیل بعد از Upgrade مهم است که:

flutter doctor -v

را بررسی کنید.

آپدیت Flutter در Windows

در Windows ابتدا PowerShell یا CMD را باز کنید:

flutter --version

سپس:

flutter channel stable

و:

flutter upgrade

در پایان:

flutter doctor -v

را اجرا کنید.

اگر Flutter پیدا نشد، مسیر نصب Flutter را با:

where flutter

بررسی کنید.

آپدیت Flutter در macOS

در macOS نیز فرآیند مشابه است:

flutter --version

سپس:

flutter channel stable
flutter upgrade

بعد:

flutter doctor -v

برای بررسی Xcode نیز:

xcodebuild -version

می‌تواند مفید باشد.

آپدیت Flutter در Linux

در Linux:

flutter --version

سپس:

flutter channel stable
flutter upgrade

و در نهایت:

flutter doctor -v

را اجرا کنید.

چگونه بفهمیم آخرین نسخه Flutter را داریم؟

بعد از آپدیت:

flutter --version

را اجرا کنید.

برای بررسی وضعیت محیط:

flutter doctor -v

همچنین می‌توانید اطلاعات Releaseهای رسمی Flutter را بررسی کنید تا ببینید نسخه Stable فعلی چیست.

Flutter Releases

آیا همیشه باید Flutter را به آخرین نسخه آپدیت کنیم؟

خیر.

در پروژه‌های Production بهتر است قبل از ارتقا، Compatibility را بررسی کنید.

اگر پروژه شما در حال توسعه فعال است، قبل از Update:

git status

را بررسی کنید و یک Commit ایجاد کنید.

مثلاً:

git add .
git commit -m "Before Flutter upgrade"

در این صورت اگر Upgrade باعث مشکل شد، امکان برگشت به وضعیت قبلی ساده‌تر خواهد بود.

بهترین زمان برای آپدیت Flutter چه زمانی است؟

برای پروژه شخصی یا آموزشی، معمولاً می‌توانید سریع‌تر به نسخه‌های جدید مهاجرت کنید.

اما برای پروژه تجاری بهتر است:

1. Release Notes را بررسی کنید.
2. Compatibility پکیج‌ها را بررسی کنید.
3. پروژه را روی Branch جداگانه Upgrade کنید.
4. تست‌ها را اجرا کنید.
5. Android و iOS Build را بررسی کنید.
6. سپس تغییرات را وارد Branch اصلی کنید.

آیا آپدیت Flutter اطلاعات پروژه را پاک می‌کند؟

خیر، اجرای معمول:

flutter upgrade

نباید کد پروژه شما را حذف کند.

با این حال، قبل از تغییر نسخه SDK بهتر است از پروژه Commit یا Backup داشته باشید.

چطور نسخه Flutter پروژه را ثابت نگه داریم؟

اگر چند پروژه دارید و هرکدام با نسخه متفاوتی از Flutter ساخته شده‌اند، استفاده از یک نسخه واحد برای همه پروژه‌ها همیشه بهترین راهکار نیست.

در پروژه‌های حرفه‌ای می‌توانید نسخه Flutter را مدیریت و Pin کنید تا تغییر نسخه SDK باعث مشکلات غیرمنتظره نشود.

ابزارهایی مانند FVM (Flutter Version Management) برای مدیریت چند نسخه Flutter روی یک سیستم کاربرد دارند.

FVM چیست؟

FVM به شما اجازه می‌دهد چند نسخه Flutter را روی یک سیستم نصب و برای هر پروژه نسخه مشخصی را انتخاب کنید.

مثلاً:

Project A → Flutter 3.x
Project B → Flutter 3.y
Project C → Flutter 3.z

این روش برای تیم‌هایی که چند پروژه با نسخه‌های متفاوت Flutter دارند بسیار کاربردی است.

چک‌لیست کامل قبل و بعد از آپدیت Flutter

قبل از Update

• Commit گرفتن از Git
• بررسی نسخه Flutter
• بررسی نسخه Dart
• بررسی Release Notes
• بررسی Compatibility پکیج‌ها
• بررسی وضعیت Android/iOS

اجرای Update

flutter channel stable
flutter upgrade

بعد از Update

flutter --version

سپس:

flutter doctor -v

و داخل پروژه:

flutter clean
flutter pub get
flutter analyze
flutter run

اگر پروژه تست دارد:

flutter test

را نیز اجرا کنید.

خلاصه دستورات مهم آپدیت Flutter

اگر فقط به دنبال سریع‌ترین روش هستید:

flutter --version

flutter channel stable

flutter upgrade

بعد:

flutter doctor -v

و در پروژه:

flutter clean
flutter pub get
flutter analyze
flutter test
flutter run

جمع‌بندی

آپدیت Flutter فقط به اجرای flutter upgrade محدود نمی‌شود. برای پروژه‌های ساده معمولاً همین دستور کافی است، اما در پروژه‌های واقعی باید بعد از ارتقای Flutter، نسخه Dart، Dependencyها، Android Gradle Plugin، Gradle، Java، Xcode و APIهای Deprecated را نیز بررسی کنید.

بهترین رویکرد برای اکثر توسعه‌دهندگان این است که از Stable Channel استفاده کنند و قبل از ارتقای Flutter از پروژه Git Commit بگیرند.

فرآیند پیشنهادی به شکل زیر است:

بررسی نسخه فعلی
       ↓
Backup / Git Commit
       ↓
بررسی Release Notes
       ↓
انتخاب Stable Channel
       ↓
flutter upgrade
       ↓
flutter doctor -v
       ↓
flutter clean
       ↓
flutter pub get
       ↓
flutter analyze
       ↓
flutter test
       ↓
flutter run

اگر بعد از Upgrade با خطا مواجه شدید، بهتر است به‌جای Downgrade یا تغییر تصادفی نسخه پکیج‌ها، ابتدا متن کامل Error را بررسی کنید؛ زیرا بسیاری از مشکلات به ناسازگاری Dependencyها یا ابزارهای Android/iOS مربوط می‌شوند.

FAQ؛ سوالات متداول آپدیت Flutter

چگونه Flutter را به آخرین نسخه آپدیت کنیم؟

ابتدا Channel را روی Stable قرار دهید:

flutter channel stable

سپس:

flutter upgrade

را اجرا کنید.

چگونه نسخه Flutter را ببینیم؟

از دستور زیر استفاده کنید:

flutter --version

چگونه نسخه Dart را بررسی کنیم؟

دستور زیر نسخه Dart نصب‌شده را نمایش می‌دهد:

dart --version

آیا با آپدیت Flutter، Dart هم آپدیت می‌شود؟

بله. Flutter SDK نسخه سازگار Dart SDK را همراه خود ارائه می‌کند؛ بنابراین معمولاً Dart همراه Flutter به‌روزرسانی می‌شود.

آیا بعد از آپدیت Flutter باید flutter clean بزنیم؟

همیشه اجباری نیست، اما در صورت وجود مشکلات Build یا تغییرات مهم نسخه SDK، اجرای flutter clean و سپس flutter pub get می‌تواند به رفع مشکلات Cache و Build کمک کند.

آیا آپدیت Flutter باعث حذف پروژه می‌شود؟

خیر. flutter upgrade برای به‌روزرسانی Flutter SDK است و نباید کد پروژه‌های شما را حذف کند. با این حال، گرفتن Git Commit قبل از Upgrade توصیه می‌شود.

چرا بعد از آپدیت Flutter پروژه اجرا نمی‌شود؟

ممکن است یکی از Dependencyها، APIهای قدیمی، Gradle، Java، Android SDK یا Xcode با نسخه جدید سازگار نباشد.

چگونه خطاهای پروژه بعد از آپدیت Flutter را پیدا کنیم؟

از این دستور استفاده کنید:

flutter analyze

همچنین:

flutter doctor -v

برای بررسی محیط توسعه مفید است.

آیا باید بعد از آپدیت Flutter همه پکیج‌ها را آپدیت کنیم؟

خیر. بهتر است ابتدا پروژه را با Dependencyهای فعلی اجرا کنید. سپس با flutter pub outdated بررسی کنید کدام پکیج‌ها نیاز به ارتقا دارند.

Stable یا Beta؛ کدام Channel Flutter بهتر است؟

برای اکثر پروژه‌های واقعی، Stable انتخاب مناسب‌تری است. Beta برای آزمایش قابلیت‌های جدیدتر مناسب است و معمولاً برای Production انتخاب اول نیست.

آیا می‌توان نسخه قبلی Flutter را دوباره نصب کرد؟

بله. می‌توان نسخه Flutter را به نسخه مشخصی تغییر داد، اما در پروژه‌های متعدد بهتر است از ابزارهای مدیریت نسخه مانند FVM استفاده کنید.