آموزشِ نَصب فِلـاتِر

آموزش نصب فلاتر در سال 2027؛ از صفر تا اجرای اولین برنامه

اگه همین الان عبارت «آموزش نصب فلاتر» رو سرچ کردی، احتمالا یه مشکل مشخص داری: یا نمی دونی چه چیزهایی باید دانلود کنی، یا فلاتر نصب شده ولی flutter doctor خطا می ده، یا اصلا Android Studio و شبیه ساز روی سیستم ضعیفت راه نمی افتن. اینجا قرار نیست با صد تا اسم عجیب گیجت کنم. با هم به ترتیب پیش می ریم و آخر کار یه برنامه واقعی رو روی گوشی یا مرورگرت اجرا می کنیم.

یه نکته رو از همین اول بگم: توی ایران ممکنه خود دانلود Flutter SDK، پکیج های Dart، ابزارهای اندروید یا Gradle به خاطر محدودیت منطقه ای و کیفیت اتصال به مشکل بخوره. پس قبل از این که هر خطایی رو بندازی گردن فلاتر، یاد می گیریم چطوری مسیر اینترنت رو هم درست بررسی کنیم. اگه می خوای نصب فلاتر در ویندوز، نصب فلاتر در لینوکس یا نصب فلاتر روی مک رو انجام بدی، بخش مربوط به سیستم خودت رو جدا بخون؛ ولی پیش نیازهای مشترک اول مقاله رو از دست نده.

برای این که بدانی چرا اصلا ارزش داره این ابزار رو یاد بگیری، یه مثال ساده: تصور کن می خوای اپ رزرو نوبت یه آرایشگاه یا کلینیک رو بسازی. با فلاتر می تونی رابط کاربری اندروید و iOS رو از یک کدبیس توسعه بدی. اما برای این که اپ واقعا به درد مشتری بخوره، بعدا باید API، ذخیره اطلاعات، خطای شبکه و مدیریت وضعیت رو هم یاد بگیری. فعلا هدفمون نصب سالم ابزارها و اولین اجراست، نه فروش رویا.

فلاتر چیه و دقیقا چه چیزی نصب می کنیم؟

فلاتر یا Flutter یه فریم ورک متن بازه که گوگل توسعه داده و با زبان Dart کار می کنه. این ابزار بهت اجازه می ده برای اندروید، iOS، وب و بعضی محیط های دسکتاپ اپ بسازی. اما این که یک کدبیس داری، به این معنی نیست که تمام قابلیت ها و افزونه های هر پلتفرم بدون تغییر همه جا اجرا می شن. مثلا دسترسی به دوربین، اعلان ها و پرداخت به تنظیمات مخصوص همون سیستم عامل نیاز داره.

وقتی درباره آموزش فلاتر حرف می زنیم، چند چیز رو از هم جدا کن: Flutter SDK ابزار اصلی ساخت پروژه است، Dart SDK همراه Flutter میاد و لازم نیست برای شروع جدا نصبش کنی، Android SDK برای ساخت اپ اندروید لازمه، VS Code فقط محیط نوشتن کده و Android Studio هم هم ادیتوره و هم راه راحتی برای مدیریت ابزارهای اندروید. خود شبیه ساز هم اختیاریه.

اگه هنوز بین دارت و فلاتر فرق قائل نیستی، بعد از راه افتادن ابزارها برو سراغ آموزش زبان دارت؛ چون بدون فهم متغیر، شرط، کلاس، Future و async/await، جلوتر موقع ساخت اپ واقعی اذیت می شی. برای دیدن نمونه های واقعی هم مقاله برنامه های ساخته شده با فلاتر رو بخون.

قبل از نصب: سیستم من فلاتر رو اجرا می کنه؟

برای کسی که «آموزش نصب فلاتر روی لپ تاپ ضعیف» رو سرچ می کنه، جواب یک عدد رم نیست. موقع تصمیم گرفتن، سه تا سؤال رو کنار هم بگذار: پروژه اندروید می خوای یا وب؟ گوشی برای تست داری یا نه؟ چقدر فضای خالی برای دانلود Android SDK و Gradle داری؟ اگر جواب ها معلوم باشه، انتخاب مسیر نصب خیلی راحت تر می شه.

مثلا اگه یه لپ تاپ دانشجویی با رم ۸ گیگ داری و گوشی اندرویدی هم دم دستته، بهتره نصب رو با VS Code و گوشی شروع کنی. این همون روش نصب فلاتر بدون شبیه ساز هست؛ نه نیاز داری AVD چند گیگی دانلود کنی، نه لازم می شه برای اولین اجرای Hello World وارد تنظیمات پیچیده گرافیک بشی. البته باز هم کامپایل پروژه ممکنه طول بکشه.

بعضی ها برای آموزش نصب فلاتر دنبال لپ تاپ با کارت گرافیک مستقل می گردن. برای اولین اپ این خرج ضروری نیست. اول ببین ابزارها روی سیستم فعلی کار می کنن یا نه. پولی که قرار بود صرف ارتقای کارت گرافیک کنی، شاید فعلا بهتر باشه صرف فضای SSD و رم بیشتر بشه؛ البته اول مدل لپ تاپ و امکان ارتقا رو بررسی کن.

سؤال معروف اینه: برای آموزش نصب فلاتر چه رم، پردازنده و کارت گرافیکی لازم دارم؟ جواب بستگی به این داره که فقط SDK و ادیتور می خوای یا Android Studio و شبیه ساز رو همزمان اجرا می کنی. سیستم مورد نیاز برای «اجرای شبیه ساز» خیلی سنگین تر از «نوشتن کد و اجرا روی گوشی واقعی» هست.

برای توسعه اندروید روی ویندوز، لینوکس یا مک به فضای خالی SSD هم فکر کن. چند گیگ فقط برای SDK فلاتر کافیه، ولی Android SDK، Gradle Cache، ایمیج شبیه ساز و پروژه ها می تونن ده ها گیگ جا بگیرن. کارت گرافیک خیلی قوی برای ساخت اولین اپ روی گوشی واقعی لازم نیست؛ ولی شتاب گرافیکی و قابلیت Virtualization برای شبیه ساز مهمن. اگه شبیه ساز بالا نمیاد، راهنمای ورود به بایوس و فعال سازی مجازی سازی هم کمکت می کنه.

اگه هدف اصلیت اپ اندرویده، گوشی واقعی بهترین راه برای فرار از بار سنگین شبیه ساز روی لپ تاپ ضعیفه. البته بیلد کردن اپ هنوز با پردازنده و رم کامپیوتر انجام می شه؛ گوشی فقط محل اجرای برنامه ست. پس هیچ کس نباید بهت قول بده با هر سیستم ۴ گیگی قطعا می تونی پروژه سنگین بسازی.

قبل از همه چیز: اینترنت ایران و تحریم شکن

وقتی دانلود مشکل داره، اول مشخص کن کدوم مرحله است: دریافت خود Flutter، گرفتن ابزارهای Android Studio، بارگیری پکیج از pub.dev یا دانلود Gradle؟ این چهار مسیر جدا هستن. در آموزش نصب فلاتر اگه همه رو با عنوان «فلاتر وصل نمی شه» قاطی کنیم، آخرش فقط چند بار نرم افزارها رو پاک و نصب می کنی و نتیجه نمی گیری.

مثلا اگر flutter --version جواب می ده ولی flutter pub get خطای pub.dev داره، لازم نیست مسیر PATH رو دوباره تغییر بدی. خود SDK پیدا شده و مشکل در دانلود وابستگی هاست. در چنین شرایطی رفع خطای flutter doctor با تشخیص مقصد خطا شروع می شه، نه با دستورهای پاک کردن کش. فایل های ناشناس رو هم فقط برای دور زدن اینترنت نصب نکن.

اگه وسط اولین پروژه پیغام دانلود از dl.google.com دیدی، بدون که Android SDK و مخازن گوگل درگیرن. تحریم شکن رو طوری تنظیم کن که هم Java و Gradle و هم ابزارهای خط فرمان بتونن ازش استفاده کنن. برای نصب فلاتر در ویندوز مخصوصا تفاوت اتصال مرورگر و PowerShell رو جدی بگیر.

این بخش بین آموزش نصب فلاتر روی هر سه سیستم عامل مشترکه. موقع نصب ممکنه به storage.googleapis.com، pub.dev، سرورهای Android SDK، مخازن Maven و Gradle وصل بشی. باز شدن سایت flutter.dev در مرورگر اصلا کافی نیست؛ ممکنه دانلودهای پشت صحنه هنوز مسدود باشن. خطای ۴۰۳ می تونه محدودیت دسترسی باشه، ولی Connection timed out، SSLHandshakeException یا Unknown host هر کدوم علت متفاوتی هم می تونن داشته باشن.

من خودم حدود یک ساله از یه سرویس تحریم شکن استفاده می کنم و برای کارم جواب داده. اگه خواستی از همون سرویس استفاده کنی، لینک دعوت شخصی من اینجاست. این لینک دعوت منه و ممکنه برای معرفی کاربر امتیاز داشته باشه. فقط شفاف بگم: من فروشنده یا پشتیبان سرویس نیستم؛ اگه قطعی، اشتراک، تنظیمات یا مشکل اتصال داشتی، باید مستقیم از پشتیبانی همون فروشنده پیگیری کنی. تجربه من هم تضمین نمی کنه که سرویس برای هر اینترنت و هر زمان دقیقا یک جور جواب بده.

روی ویندوز و لینوکس، برای این کار از v2rayN استفاده می کنم و موقع دانلود ابزارهای توسعه حالت TUN رو روشن می کنم تا برنامه های بیشتری از مسیر اتصال عبور کنن. نکته مهم اینه که فعال کردن TUN ممکنه نیاز به مجوز مدیریتی داشته باشه و بسته به نسخه برنامه، هسته و توزیع لینوکس درست کار نکنه. پس بعد از فعال کردنش اتصال رو تست کن، نه این که صرفا به سبز شدن آیکن برنامه اعتماد کنی. روی مک هم باید از کلاینت سازگار همون سیستم استفاده کنی؛ لزوما اسم و گزینه هاش مثل ویندوز نیست.

یه راه دیگه که بعضی کاربرها استفاده می کنن سرویس DNS به اسم «شکن» هست. طبق تجربه ای که من در زمان آماده کردن این آموزش دارم، پلن رایگانش برای دانلودهای فلاتر برام جواب نداده و باید پلن پولی رو بررسی کرد. با این حال وضعیت فعال بودن طرح ها و پوشش دامنه ها ممکنه تغییر کنه؛ قبل از خرید از سایت رسمی خود سرویس بررسی کن. تازه DNS و تحریم شکن سیستمی دقیقا یک کار انجام نمی دن. DNS به تنهایی تمام ترافیک Gradle و Android Studio رو از یک تونل عبور نمی ده.

قبل از نصب، اتصال به دامنه های کلیدی رو بررسی کن. این چند دستور فقط پاسخ شبکه رو نشون می دن؛ با موفق بودنشون هم تضمین نمی شه دانلود تمام مخازن اندروید باز باشه.

curl -I --max-time 15 https://pub.dev
curl -I --max-time 15 https://storage.googleapis.com
curl -I --max-time 15 https://dl.google.com

روی ویندوز این دستورها رو در PowerShell جدید اجرا کن. اگر داخل خط فرمان قدیمی دستور curl رفتارش فرق داشت، از curl.exe استفاده کن. روی لینوکس و مک همون curl کافیه. کد 403 یا 301 رو با قطع اینترنت یکی ندون؛ وضعیت HTTP و خطای TLS رو جدا ببین.

اگه اینترنتت از یه پراکسی فقط مخصوص مرورگر رد می شه، VS Code، Flutter، Java و Gradle شاید بدون پراکسی به اینترنت وصل شن. اول TUN یا پروکسی سیستمی رو بررسی کن. در بعضی شرایط می شه پراکسی رو برای ابزارها جدا تنظیم کرد، ولی چون نوع و پورت هر سرویس فرق داره، از نوشتن آدرس ثابت و حدسی توی تنظیمات Gradle خودداری کن.

برای مشکل دریافت پکیج های Dart، خود تیم Flutter راهنمای استفاده از میرورهای جامعه کاربری هم داره؛ مثلا سرورهای مخصوص چین. اینها راه جایگزین هستن، نه اینکه از طرف Flutter تضمین امنیت و در دسترس بودن داشته باشن. موقع استفاده از میرور، هم منبع بسته و هم خطر دستکاری زنجیره تامین رو جدی بگیر. راهنمای رسمی رو از این صفحه فلاتر ببین.

اگه اینترنت بین الملل کاملا قطع شده و فقط دسترسی محدود داری، ما یه راهنمای جدا درباره فلاتر با نت ملی هم داریم که درباره آماده کردن فایل ها و کش ها از قبل صحبت می کنه. ولی یادت باشه فایل های Android SDK، Flutter و Gradle باید از نظر نسخه و معماری با هم سازگار باشن؛ هیچ بسته آفلاینی برای تمام سیستم ها و تمام پروژه ها تضمین صددرصدی نیست. برای شناخت گزینه های جایگزین هم مقاله مخازن داخلی برای برنامه نویسان رو بخون.

نصب فلاتر در ویندوز ۱۱ و ۱۰

قبل از این که چیزی نصب کنی، تصمیم بگیر کدوم روش رو ترجیح می دی. نصب فلاتر در ویندوز از طریق VS Code برای شروع راحت تره چون خود افزونه مسیر SDK رو می سازه؛ روش ZIP برای کسی خوبه که دانلود رو از سیستم دیگه منتقل کرده یا می خواد مسیر پوشه رو کامل خودش کنترل کنه. یکی رو انتخاب کن، هر دو رو روی هم نصب نکن.

ازم زیاد می پرسن آیا آموزش نصب فلاتر یعنی حتما باید Android Studio رو ساعت ها باز نگه داریم؟ نه. برای نوشتن کد از VS Code استفاده کن؛ Android Studio می تونه ابزار مدیریت SDK باشه. البته وقت نصب پکیج های جدید یا ساخت Emulator دوباره بهش برمی گردی.

توی نصب فلاتر در ویندوز، آدرس هایی مثل C:\src\flutter فقط مثالن. اصل ماجرا اینه که پوشه SDK قابل نوشتن باشه، اسم مسیر خیلی پیچیده نباشه و bin توی PATH درست قرار بگیره. اگه SDK از قبل داری، حذف عجولانه اش به خاطر خطای PATH معمولا فقط وقتت رو می گیره.

بریم سراغ نصب فلاتر در ویندوز. برای ویندوز، ساده ترین روش مورد توصیه مستندات جدید Flutter اینه که از داخل VS Code و افزونه Flutter، خود SDK رو دریافت و PATH رو تنظیم کنی. من این مسیر رو اول می گم؛ بعد روش دستی رو هم می نویسم تا اگر دانلود اتوماتیک در ایران گیر کرد دستت بسته نباشه.

قدم اول ویندوز: Git و VS Code

اول Git for Windows و VS Code رو نصب کن. Git برای دریافت کد و بخشی از گردش کار فلاتر به درد می خوره. اگه تازه کار هستی، بیشتر گزینه های پیش فرض نصب Git مناسبن. بعد VS Code رو باز کن، در بخش Extensions عبارت Flutter رو سرچ کن و افزونه ناشر Dart Code رو نصب کن. افزونه Dart هم همراهش نصب می شه.

این جا یه اشتباه پرتکرار هست: صرفا نصب افزونه Flutter به معنی نصب SDK نیست. باید خود Flutter SDK هم روی دیسک قرار بگیره؛ وگرنه دستور flutter شناخته نمی شه.

قدم دوم ویندوز: نصب پیشنهادی Flutter داخل VS Code

در VS Code کلیدهای Ctrl + Shift + P رو بزن، عبارت Flutter: New Project رو انتخاب کن. اگه مسیر SDK خواست، Download SDK رو بزن. مسیر قابل نوشتن مثل C:\src یا پوشه develop داخل حساب کاربری خودت رو انتخاب کن و Clone Flutter رو بزن. بعد از دانلود، گزینه Add SDK to PATH رو تایید کن. ترمینال های قدیمی و VS Code رو کامل ببند و دوباره باز کن.

اگه این دانلود به خاطر اینترنت ایران متوقف شد، اصرار نکن چند بار بی نتیجه دکمه بزنی. اتصال رو با توضیحات تحریم شکن اول مقاله بررسی کن و در صورت نیاز سراغ روش دستی مرحله بعد برو. نصب از مسیر C:\Program Files معمولا انتخاب خوبی نیست چون مجوز نوشتن محدودتری داره.

قدم سوم ویندوز: نصب دستی با ZIP یا Git

برای نصب دستی از آرشیو رسمی SDK فایل stable ویژه Windows و معماری دستگاهت رو دانلود کن. فایل ZIP رو مثلا جایی باز کن که ساختار نهایی پوشه به شکل C:\src\flutter\bin باشه؛ مراقب پوشه تودرتوی flutter\flutter باش. اگه دانلود ZIP از مخزن اصلی مشکل داشت، قبل از هر سایت واسطه ای درباره منبع فایل و صحتش تحقیق کن.

روش دیگه کلون کردن مخزن رسمی Flutter هست. این دستور رو در PowerShell اجرا کن؛ اگر پوشه C:\src\flutter از قبل وجود داره، دوباره روش کلون نکن.

git clone --branch stable https://github.com/flutter/flutter.git C:\src\flutter

برای روش دستی باید مسیر C:\src\flutter\bin رو به متغیر User Path اضافه کنی. توی Start دنبال Environment Variables بگرد، بخش Environment Variables رو باز کن، زیر User variables روی Path و بعد New بزن، مسیر پوشه bin رو اضافه کن، همه پنجره ها رو OK کن و PowerShell جدید باز کن. مسیر واقعی نصب خودت رو جایگزین کن؛ لازم نیست فایل های SDK رو به صورت دستی تغییر بدی.

flutter --version
dart --version
where.exe flutter

اگه where.exe flutter چند مسیر نشون داد، ممکنه چند Flutter SDK روی ویندوزت باشه و یکی نسخه قدیمی رو اجرا کنه. قبل از حذف هر چیزی، مسیر اول رو با پوشه ای که تازه نصب کردی مقایسه کن. نصب فلاتر در ویندوز وقتی کامل می شه که هم فرمان اجرا بشه و هم تست پلتفرم مورد نظرت درست باشه.

قدم چهارم ویندوز: Android Studio و Android SDK

حالا اگه می خوای اپ اندروید بسازی، نوبت Android Studio می رسه. برای نصب فلاتر در ویندوز، داشتن VS Code کافی نیست که خروجی اندروید بگیری؛ ابزارهای Android SDK و مجوزها رو هم لازم داری. Android Studio رو نصب کن، اولین بار بازش کن و Setup Wizard رو تا پایان برو تا اجزای لازم دریافت بشن. اگه دانلود متوقف شد، وضعیت تحریم شکن و خطاهای SDK Manager رو بررسی کن.

از صفحه خوشامد Android Studio وارد More Actions > SDK Manager شو؛ یا وقتی پروژه بازه از Tools > SDK Manager استفاده کن. در SDK Platforms یک نسخه پلتفرم سازگار با Flutter و پروژه ات رو نصب کن. در SDK Tools وجود Android SDK Command-line Tools (latest)، Android SDK Build-Tools و Android SDK Platform-Tools رو چک کن. ابزارهای دیگه مثل NDK و CMake رو طبق نیاز و مستندات نسخه فعلی اضافه کن؛ هر پروژه ای از همون روز اول به همه اونها احتیاج نداره.

حالا دستورات زیر رو بزن. مجوزهای اندروید رو بخون و در صورت موافقت تایید کن. اگر cmdline-tools component is missing دیدی، قبل از هر چیز برگرد SDK Manager و Command-line Tools رو نصب کن.

flutter doctor --android-licenses
flutter doctor -v

در خروجی flutter doctor فقط اخطارهای مربوط به مقصد خودت رو رفع کن. مثلا اگه هدف فعلا اندرویده، خطای نبودن Visual Studio برای خروجی دسکتاپ ویندوز مانع ساخت اپ اندروید نیست. اگر بعدا خواستی برنامه دسکتاپ Windows بسازی، باید Visual Studio کامل با بخش Desktop development with C++ رو هم نصب کنی؛ VS Code جای اون ابزار رو نمی گیره.

نصب فلاتر در لینوکس؛ اوبونتو، دبیان و بقیه

اگر هدفت نصب فلاتر در لینوکس روی Ubuntu یا Debian هست، یه تفاوت مهم رو بدون: فرمان apt فقط پیش نیازهای سیستم رو نصب می کنه؛ خود Flutter SDK رو باید با روش رسمی VS Code، آرشیو stable یا Git بگیری. بعضی آموزش ها این دو مرحله رو با هم قاطی می کنن و دانشجو بعد از نصب چند بسته انتظار داره flutter اجرا بشه.

در نصب فلاتر در لینوکس من پیشنهاد می کنم SDK رو داخل پوشه home کاربر خودت نگه داری تا بروزرسانی معمولی نیاز به sudo نداشته باشه. کار کردن هر روزه با ابزار توسعه تحت root نه لازم هست و نه انتخاب خوبی برای امنیت سیستم.

یک مشکل رایج نصب فلاتر در لینوکس، فرق داشتن Bash و Zsh یا Fish هست. شاید مسیر Flutter رو به .bashrc اضافه کرده باشی ولی ترمینالت Zsh باز می کنه. قبل از نصب دوباره، با echo $SHELL بفهم شل فعلیت چیه و فایل تنظیمات مرتبطش رو درست کن.

اگه روی Linux نصب رو با گوشی اندروید جلو می بری، ممکنه خروجی flutter devices خالی باشه اما ایراد از Flutter نباشه. اول خروجی adb devices رو چک کن، بعد قوانین USB و مجوزهای کاربر رو بررسی کن. این مسیر برای خیلی ها از اجرای شبیه ساز روی سیستم کم رم راحت تره.

برای نصب فلاتر در لینوکس، اول نوع توزیع و پردازنده ات رو مشخص کن. من دستورهای این بخش رو برای Ubuntu و Debian می نویسم؛ روی Fedora و Arch اسم بسته ها و مدیر بسته فرق داره. اگر هنوز لینوکس نصب نکردی، آموزش نصب اوبونتو رو ببین. یادت باشه اندروید استودیو و شبیه ساز روی یک توزیع سبک هم می تونن کلی رم مصرف کنن.

ابتدا ابزارهای پایه رو نصب کن. بعد VS Code و افزونه Flutter رو از منبع رسمی دریافت کن و همون مسیر Flutter: New Project > Download SDK رو برو. اگر خواستی دستی نصب کنی، می تونی آرشیو Linux stable رو از سایت رسمی دانلود و در ~/develop استخراج کنی یا مخزن Git رو کلون کنی.

sudo apt update
sudo apt install -y curl git unzip xz-utils zip libglu1-mesa

این دستور نمونه روش Git هست. قبل از اجرا مطمئن شو پوشه مقصد از قبل وجود نداره. اگر دانلود گیت به خاطر محدودیت شبکه متوقف شد، روش آرشیو رسمی و تحریم شکن سیستمی رو بررسی کن.

mkdir -p "$HOME/develop"
git clone --branch stable https://github.com/flutter/flutter.git "$HOME/develop/flutter"

در Bash، مسیر Flutter رو به ~/.bashrc اضافه کن. اگر از Zsh یا Fish استفاده می کنی، فایل تنظیمات اون شل فرق داره. این کد مخصوص Bash هست.

echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> "$HOME/.bashrc"
source "$HOME/.bashrc"
flutter --version
flutter doctor -v

بعد Android Studio لینوکس رو از سایت رسمی بگیر و Wizard نصب ابزارهای اندروید رو کامل کن. مسیر SDK رو اگر خود Flutter پیدا نکرد از گزارش flutter doctor -v بررسی کن؛ قبل از تغییر دستی فایل های پروژه، اجازه بده نصب کامل بشه. اگه علاوه بر اندروید، خروجی دسکتاپ Linux می خوای، بسته های مخصوص ساخت برنامه های بومی رو هم نصب کن.

sudo apt install -y clang cmake ninja-build pkg-config libgtk-3-dev libstdc++-12-dev

برای گوشی اندرویدی در لینوکس، علاوه بر روشن بودن USB debugging، ممکنه لازم بشه قوانین udev یا مجوز دسترسی USB رو تنظیم کنی. اگر adb devices گوشی رو با وضعیت no permissions نشون داد، اول قوانین مربوط به دستگاه و گروه کاربری رو از مستندات توزیعت بررسی کن؛ اجرای دائمی Android Studio با root راه حل نیست.

در مورد تحریم شکن روی لینوکس هم دوباره تاکید کنم: من از v2rayN در حالت TUN استفاده می کنم، ولی بعضی نسخه ها با بعضی توزیع ها ناسازگاری یا نیاز به دسترسی سیستمی دارن. قبل از دانلود Gradle و SDK، اتصال از ترمینال رو بررسی کن و با روشن بودن رابط گرافیکی خیال خودت رو راحت نکن.

نصب فلاتر روی مک؛ Intel و Apple Silicon

برای نصب فلاتر روی مک اول ببین تراشه دستگاهت M1/M2 یا نسل های جدید Apple Silicon هست یا Intel. فایل نصبی و ابزارهای وابسته می تونن برای این دو معماری متفاوت باشن. اشتباه انتخاب کردن آرشیو معمولا با دانلود دوباره حل می شه، ولی تغییر نسخه Xcode بدون توجه به macOS ممکنه دردسر درست کنه.

یه سؤال پرتکرار درباره نصب فلاتر روی مک اینه که آیا Xcode برای همه اپ ها لازمه؟ اگه فقط خروجی اندروید می خوای، Android Studio و SDK اندروید مسیر اصلی تو هستن. برای خروجی iOS، ابزارهای Xcode و قراردادهای امضای اپ وارد کار می شن. همین تفکیک ساده باعث می شه چندین گیگ بی دلیل نصب نکنی.

اگه نصب فلاتر روی مک با command not found گیر کرد، اول فایل .zprofile و مسیر پوشه flutter/bin رو بررسی کن. در نسخه های جدید macOS پوسته پیش فرض عموما Zsh هست؛ کپی کردن دستورات Bash از یک آموزش قدیمی ممکنه توی ترمینال تو اثر مورد انتظار رو نداشته باشه.

برای نصب فلاتر روی مک هم اول مسیر رو مشخص کن: فقط می خوای اپ اندروید بسازی یا iOS هم می خوای؟ برای ساخت و تست خروجی iOS به macOS و Xcode نیاز داری. ویندوز و لینوکس به تنهایی جای یک محیط رسمی ساخت iOS رو نمی گیرن. فلاتر برای Apple Silicon و مک های Intel بسته های معماری متفاوت داره و پشتیبانی Intel در حال تغییر و محدود شدن هست؛ قبل از دانلود نسخه مناسب رو از بخش About This Mac و مستندات رسمی بررسی کن.

اگر Xcode Command Line Tools رو نداری نصبش کن. بعد VS Code و افزونه Flutter رو نصب کن و از Command Palette گزینه Flutter: New Project و Download SDK رو انتخاب کن. اگر دستی نصب کردی، پوشه SDK رو مثلا در ~/develop/flutter نگه دار و برای Zsh مسیر bin رو به ~/.zprofile اضافه کن.

xcode-select --install

دستور بالا ممکنه روی مک هایی که Command Line Tools دارن پیغام بده که از قبل نصب شده؛ در این صورت ایرادی نیست. برای روش دستی بعد از استخراج Flutter به پوشه home می تونی مسیر رو این طوری ثبت کنی:

echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> "$HOME/.zprofile"
source "$HOME/.zprofile"
flutter --version
flutter doctor -v

اگه فقط برای اندروید کار می کنی، نصب Android Studio و ابزارهای Android SDK مشابه بخش ویندوزه. ولی اگر قصد داری اپ iPhone یا iPad بسازی، باید نسخه سازگار Xcode رو از منبع رسمی نصب کنی، مجوزش رو تایید کنی، ابزارهای Command Line رو به Xcode متصل کنی و در صورت نیاز ابزارهای مدیریت وابستگی iOS مثل CocoaPods رو هم نصب کنی. نحوه آماده سازی با نسخه Xcode و پلاگین های پروژه تغییر می کنه؛ از راهنمای رسمی iOS فلاتر پیش برو.

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
xcodebuild -version

این دستورات فقط وقتی معنی دارن که Xcode کامل نصب شده باشه، نه صرفا Command Line Tools. شبیه ساز iPhone از ابزارهای Xcode اجرا می شه، اما برای خروجی اندروید به Android Emulator یا گوشی اندرویدی نیاز داری. اگه مک Intel داری، حتما هشدارهای آینده پشتیبانی نسخه های جدید Flutter و Android Studio رو قبل از به روزرسانی بررسی کن.

بدون شبیه ساز: گوشی اندرویدی خودت رو وصل کن

برای کسی که نصب فلاتر بدون شبیه ساز رو می خواد، این نکته رو هم روشن کنم: گوشی باید نسخه اندروید سازگار با پروژه رو داشته باشه و به کامپیوتر اجازه دیباگ بده. موبایل هرچقدر هم قوی باشه، جای Android SDK رو نمی گیره. کامپیوتر همچنان باید ابزار ساخت اپ رو داشته باشه.

وقتی از گوشی واقعی استفاده می کنی، همون اول یه اپ ساده اجرا کن و کابل رو جدا نکن تا اولین تست تموم بشه. بعدا می تونی سراغ دیباگ بی سیم بری. این ترتیب برای آموزش نصب فلاتر خیلی بهتر از اینه که از دقیقه اول USB، شبکه و شبیه ساز رو همزمان تنظیم کنی.

به نظرم این قسمت برای دانشجوهایی که با لپ تاپ اقتصادی کار می کنن از همه مهم تره. نصب فلاتر بدون شبیه ساز کاملا ممکنه. یعنی به جای این که یه گوشی مجازی سنگین داخل کامپیوتر اجرا کنی، برنامه رو روی گوشی اندرویدی خودت می فرستی. باز هم ساخت برنامه روی کامپیوتر انجام می شه، ولی برای اجرا بار اضافه شبیه ساز رو نداری.

اول برو تنظیمات گوشی، بخش About phone و روی Build number معمولا هفت بار بزن تا Developer options فعال بشه. مسیر دقیق این گزینه در گوشی سامسونگ، شیائومی، پیکسل و برندهای دیگه یکی نیست. بعد از داخل Developer options، گزینه USB debugging رو روشن کن. گوشی رو با کابل سالمی که انتقال دیتا پشتیبانی می کنه به کامپیوتر وصل کن. وقتی پیغام اعتماد به کامپیوتر رو دیدی، فقط اگر دستگاه خودته تایید کن.

اگه در ویندوز گوشی پیدا نشد، ممکنه درایور USB مخصوص سازنده لازم باشه. در لینوکس مجوز udev رو چک کن. در مک معمولا درایور USB ویندوزی لازم نیست. برای این که معلوم بشه گوشی واقعا شناسایی شده، اول adb devices و بعد flutter devices رو اجرا کن.

adb devices
flutter devices

وقتی جلوی اسم گوشی unauthorized دیدی، صفحه موبایل رو باز کن و درخواست USB debugging رو تایید کن. اگر اصلا چیزی نیومد، کابل، پورت، حالت USB و درایور رو بررسی کن. با انتخاب Revoke USB debugging authorizations توی Developer options می تونی اجازه قبلی رو لغو کنی و دوباره مجوز بدی. با پایان کار هم بهتره USB debugging رو خاموش کنی.

بعدا می تونی از Wireless debugging هم استفاده کنی، اما برای اولین نصب بهتره کابل USB رو انتخاب کنی تا هم اشکال شبکه و هم اشکال اتصال گوشی رو با هم قاطی نکنی.

ساخت شبیه ساز اندروید برای سیستم مناسب

اگه رم کافی داری و می خوای روی اندازه های مختلف گوشی تست کنی، Android Emulator هم ابزار خوبیه. توی Android Studio برو به Tools > Device Manager، گزینه Create Virtual Device رو انتخاب کن، یک گوشی معمولی انتخاب کن، ایمیج Android سازگار رو دانلود کن و شبیه ساز رو اجرا کن. دانلود ایمیج ها هم ممکنه از ایران به تحریم شکن نیاز داشته باشه.

برای این مرحله بهتره حداقل ۱۶ گیگ رم و فضای خالی مناسب داشته باشی. اگر خطای شتاب دهنده گرفتی، از BIOS یا UEFI وضعیت Intel VT-x یا AMD-V رو چک کن. روی ویندوز نوع Hypervisor و قابلیت های مجازی سازی هم اثر دارن. اگر شبیه ساز کند بود، اول به جای بالا بردن بی دلیل رم VM، یک گوشی واقعی تست کن.

flutter doctor؛ از کجا بفهمم نصب درست شده؟

برای رفع خطای flutter doctor اول از خودت بپرس کدوم مقصد رو می خوای: Android، iOS، Web، Windows یا Linux Desktop؟ خطای Xcode روی ویندوز معنی نداره و هشدار Visual Studio وقتی فقط روی گوشی اندروید کار می کنی لزوما مانع تو نیست. فرق خطای واقعی با هشدار مربوط به پلتفرم دیگه رو یاد بگیر.

روش درست رفع خطای flutter doctor اینه که یک بار با -v اجراش کنی، اولین مورد مربوط به مقصد خودت رو پیدا کنی و همون رو حل کنی. مثلا اگه Android SDK ناقصه، فعلا سراغ پاک کردن Flutter SDK نرو. به جای تغییر همزمان پنج تنظیم، هر بار فقط یک علت رو بررسی کن.

بعد از رفع خطای flutter doctor، دوباره flutter devices رو اجرا کن. سالم شدن ابزارها به معنی شناسایی گوشی نیست. اگر ابزارهای Android سالم باشن اما گوشی در لیست نباشه، مسیر خطا از نصب به اتصال دستگاه منتقل شده؛ پس سراغ کابل، درایور و USB debugging برو.

الان وقت تشخیص واقعیه. آموزش نصب فلاتر وقتی تموم می شه که بدونی چه چیزی سالمه و چه چیزی هنوز کم داری. رفع خطای flutter doctor رو هم از همین گزارش شروع کن. فرمان رو با حالت جزئیات اجرا کن و ببین کدام بخش علامت ضربدر داره. اشتباه رایج اینه که هر ضربدر رو یک فاجعه می دونن؛ در حالی که شاید اصلا قصد توسعه اون پلتفرم رو نداری.

flutter doctor -v
flutter devices
flutter emulators

اگه Android toolchain ایراد داشت، اول SDK Manager و مجوزها رو بررسی کن. اگر Chrome نبود و فقط می خوای اپ اندروید بسازی، فوری نرو مرورگر نصب کن. اگر Visual Studio برای Windows desktop علامت قرمز داشت، به معنی خراب بودن ساخت اندروید نیست. این تفاوت باعث می شه بی دلیل چند گیگ نرم افزار اضافی نصب نکنی.

اولین پروژه فلاتر رو اجرا کنیم

اگه تا اینجا اومدی و ابزارهای لازم سالم هستن، از اینجا به بعد باید نتیجه رو ببینی. من یه پروژه خیلی ساده درست می کنم، روی گوشی یا Chrome اجراش می کنم و بعد تغییر متن داخل صفحه رو می بینم. این قدم کوچیک کمک می کنه تفاوت بین نصب SDK و ساخت واقعی اپ رو بفهمی.

flutter create my_first_app
cd my_first_app
flutter devices
flutter run

در دستور آخر اگر چند دستگاه شناسایی شد، از لیست یکی رو انتخاب کن یا گزینه -d رو با شناسه واقعی دستگاه اجرا کن. برای Chrome می تونی بنویسی flutter run -d chrome. اولین بیلد اندروید ممکنه طولانی باشه، چون Gradle و وابستگی ها رو دانلود می کنه؛ مدت ثابتی برای همه دستگاه ها وجود نداره.

flutter run -d chrome

حالا فایل lib/main.dart رو در VS Code باز کن. اگه دوست داری به جای برنامه شمارنده آماده، یه برنامه خیلی کوچیک و تمیز داشته باشی، این کد رو جایگزین کن و دوباره اجرا کن. این مثال از ویجت های خود Flutter استفاده می کنه و پکیج اضافه ای نیاز نداره.

import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('My First Flutter App')),
        body: const Center(child: Text('Hello from Flutter!')),
      ),
    );
  }
}

در طول اجرا با ذخیره تغییرات و Hot Reload می تونی نتیجه رو ببینی. اگر تست روی گوشی واقعی انجام می دی، با خاموش کردن تحریم شکن در وسط اولین بیلد ممکنه دانلود وابستگی ها متوقف بشه. بعد از این که پروژه ساخته شد می تونی سراغ Widgetها، چیدمان، فرم ها و API بری.

رفع خطاهای پرتکرار نصب فلاتر

خطای flutter is not recognized و مشکل PATH

اگه ویندوز نوشت flutter is not recognized یا لینوکس و مک گفتن command not found، یعنی مسیر flutter/bin به PATH فعال نرسیده یا ترمینال قدیمیه. آدرس SDK رو دوباره چک کن، ترمینال رو ببند و باز کن و تست نسخه رو بزن. نصب مجدد همه ابزارها معمولا اولین راه حل خوبی نیست.

مشکل Resolving dependencies و TLS یا 403

این مورد مخصوصا توی ایران زیاد می بینیم. ممکنه flutter pub get روی Resolving dependencies بمونه یا TLS handshake failed بده. اول ببین pub.dev و مخازن دیگه از ترمینال قابل دسترسی هستن یا نه. اگر مرورگر باز می کنه ولی خط فرمان نه، به تنظیمات پراکسی و TUN برگرد. برای هر ۴۰۳ هم فورا کش و SDK رو پاک نکن.

flutter pub get
flutter doctor -v

مشکل Gradle و دانلود از Google Maven

گاهی خود فلاتر سالمه ولی موقع اجرای اندروید خطایی مثل Could not resolve، dl.google.com یا services.gradle.org ظاهر می شه. اینجا مشکل از دانلود وابستگی های اندرویده، نه از PATH فلاتر. اتصال همون دامنه خطا رو تست کن؛ مطمئن شو Gradle در حالت Offline نیست و تحریم شکن فقط محدود به مرورگر نیست. بدون فهم خطا، فایل های gradle-wrapper.properties یا مخازن رسمی رو با لینک ناشناس جایگزین نکن.

cmdline-tools component is missing و Android license

برای این دو مشکل اول Android Studio رو باز کن و از SDK Manager وجود Command-line Tools و پلتفرم اندروید رو بررسی کن. بعد مجوزها رو تایید کن. اگر چند JDK روی سیستم داری، ممکنه Java نامناسب باعث خطا بشه؛ قبل از تغییر JAVA_HOME، نسخه مورد استفاده Gradle رو در گزارش خطا ببین. نسخه Java مورد نیاز پروژه با نسخه ابزارها تغییر می کنه.

flutter doctor --android-licenses
flutter doctor -v

No devices found و unauthorized

این خطا معمولا یعنی نه شبیه ساز بالا اومده و نه گوشی با مجوز USB debugging دیده شده. کابل دیتادار، تایید مجوز روی گوشی، درایورهای ویندوز و قوانین دسترسی لینوکس رو بررسی کن. اگه با adb devices هیچ چیزی نمی بینی، اول همون مشکل اتصال رو حل کن و بعد برگرد Flutter.

مشکل شبیه ساز: HAXM، Hypervisor و صفحه سیاه

آموزش های خیلی قدیمی هنوز برای هر دستگاهی HAXM پیشنهاد می دن؛ ولی راهکار شتاب دهنده با نوع پردازنده، سیستم عامل و نسخه Emulator فرق کرده. از راهنمای فعلی Android Emulator و ابزارهای خود Android Studio استفاده کن. برای لپ تاپ ضعیف، گوشی واقعی اغلب انتخاب عملی تریه تا درگیر تنظیمات پیچیده مجازی سازی نشی.

Failed to find Android SDK و چند SDK مختلف

اگه Flutter پوشه Android SDK رو پیدا نکرد، اول مسیر SDK رو در Android Studio ببین و با مسیر داخل گزارش flutter doctor -v مقایسه کن. روی ویندوز معمولا داخل پوشه کاربری قرار داره، ولی حدس زدن مسیر روی همه کامپیوترها اشتباهه. وقتی مطمئن شدی محل صحیح کجاست، در صورت نیاز به Flutter مسیر صحیح رو معرفی کن.

flutter config --android-sdk "/path/to/Android/Sdk"

این مسیر فقط نمونه است؛ باید آدرس واقعی Android SDK سیستم خودت رو بنویسی. برای نمونه روی ویندوز معمولا مسیری از جنس C:\Users\USERNAME\AppData\Local\Android\Sdk و روی لینوکس ~/Android/Sdk وجود داره. هیچ مسیری رو کورکورانه کپی نکن.

مشکل نصب فلاتر روی مک و نبودن Xcode

اگه flutter doctor خطای Xcode می ده ولی قصدت فقط اندرویده، اول بررسی کن واقعا به خروجی iOS نیاز داری یا نه. اگه هدفت اپ آیفونه، Xcode کامل و نسخه سازگار با macOS رو نصب کن و راهنمای رسمی iOS رو دنبال کن. کپی کردن پوشه Xcode از دستگاه ناشناس یا استفاده از فایل های دستکاری شده کار امنی نیست.

به روزرسانی Flutter بدون خراب کردن پروژه

وقتی پروژه سالم کار می کنه، لازم نیست هر روز به خاطر انتشار نسخه تازه همه چیز رو آپدیت کنی. برای شروع از کانال stable استفاده کن. قبل از آپدیت پروژه مهم، تغییرات نسخه ها، سازگاری پکیج ها و فایل pubspec.lock رو بررسی کن. روی پروژه واقعی از Git استفاده کن تا اگه آپدیت به مشکل خورد راحت تر بفهمی چه چیزی تغییر کرده.

flutter channel stable
flutter upgrade
flutter --version
flutter doctor -v

اگه بعد از آپدیت Gradle یا پکیجی خطا داد، متن همون خطا رو بخون و اول مشکل سازگاری رو پیدا کن. پاک کردن کل پوشه SDK، حذف همه کش ها یا نصب دوباره Android Studio معمولا باید آخرین راه باشه، نه اولین واکنش.

بعد از نصب فلاتر، چی یاد بگیرم؟

یه نکته مهم درباره آموزش فلاتر اینه که لازم نیست فقط با کپی کردن UI جلو بری. وقتی یه صفحه ساده ساختی، سعی کن وضعیت لود شدن، پیام خطای اینترنت و ذخیره اطلاعات رو بهش اضافه کنی. همین تمرین های کوچک باعث می شن وقتی وارد پروژه جدی شدی، کنترل بیشتری روی رفتار برنامه داشته باشی.

اگه تازه با این فریم ورک آشنا شدی، مقاله ۶ ویژگی جالب فلاتر و ۵ دلیل برای یادگیری فلاتر رو بخون. برای زبان برنامه نویسی هم ۱۰ ویژگی زبان دارت و تفاوت Null Safety و Sound Null Safety موضوع های خوبی هستن. هدف از لینک ها اینه که هر بخش رو وقتی لازمت شد عمیق تر یاد بگیری، نه اینکه وسط نصب فلاتر مدام از مسیر اصلی خارج بشی.

وقتی آموزش فلاتر رو جدی دنبال کنی، کم کم می فهمی یک خروجی خوشگل با یک اپ قابل تحویل فرق داره. این دقیقا همون جاییه که یادگیری API، خطایابی، معماری و مدیریت وضعیت کمک می کنه اپ واقعی برای بازار ایران بسازی.

تا اینجا فقط محیط رو راه انداختیم. این که برنامه نمونه اجرا شد عالیه، ولی فاصله زیادی بین یه صفحه Hello و اپی هست که واقعا برای کاربر ارزش داشته باشه. از اینجا به بعد باید Dart، ساخت Widget، دریافت داده از API، مدیریت خطا، State، ذخیره سازی و تست رو یاد بگیری. مثلا ساخت یه اپ ثبت سفارش برای فروشگاه ایرانی فقط طراحی چند تا دکمه نیست؛ باید اینترنت قطع شد، کاربر چند بار دکمه زد یا پرداخت ناموفق بود، باز هم درست رفتار کنه.

برای همین پیشنهاد من اینه که بعد از اولین اجرا، با یادگیری دارت شروع کنی و بعد سراغ مسیر پروژه محور فلاتر بری؛ سرفصل ها و نمونه تدریس رو ببین و خودت تصمیم بگیر چه آموزشی کمکت می کنه. اگه هنوز مطمئن نیستی این حرفه مناسبته، مقاله چطوری برنامه نویس بشیم کمک می کنه مسیرهای مختلف رو مقایسه کنی. اینجا قرار نیست فقط چون نصب ابزار سخته، فکر کنی باید حتما دوره بخری؛ اول ببین با ساختن محصول واقعا ارتباط می گیری یا نه.

یه تمرین واقعی برای خودت تعریف کن: یه اپ لیست کارها بساز که بتونی اطلاعات رو اضافه، حذف و ذخیره کنی. بعد نسخه دومش رو به API وصل کن. وقتی برای هر مشکل جدید فقط منتظر کپی کردن کد آماده نباشی و دلیل کارکردش رو بفهمی، می بینی برنامه نویسی چقدر جذاب تر می شه.

ویدیوی آموزش نصب فلاتر

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

سوالات متداول نصب فلاتر

جمع بندی؛ از نصب فلاتر تا اولین پروژه

حالا که نصب انجام شده، وقت ساختنه. یه اپ ساده برای خودت بساز، یه باگ واقعی پیدا کن و حلش کن. همون روزی که اولین خطای شبکه یا رابط کاربری رو خودت رفع کنی، می فهمی چرا یادگیری فلاتر فقط نصب چند تا نرم افزار نیست.