السلسلة: هذا الدرس جزء من سلسلة Flutter. اقرأ المقال الرئيسي.

قبل كتابة أي سطر Dart، بيئة Flutter يجب أن تكون نظيفة وكاملة. هذا الدرس يُرافقك خطوة بخطوة في تثبيت Flutter 3.41 وDart 3.11، ضبط Android Studio، قبول licenses SDK، وتشغيل أول مشروع على emulator Android. في النهاية، flutter doctor لن يُبلّغ أي خطأ.

المتطلبات

نظام التشغيل: Windows 10 1903+ (64 بت)، macOS 12 Monterey أو أحدث، أو توزيعة Linux 64 بت (Ubuntu 22.04 LTS موصى به)
16 جيغا RAM موصى به (8 حد أدنى)، 40 جيغا قرص حر
Git مثبَّت ومتاح في PATH
اتصال إنترنت مستقرّ لتنزيل ~3 جيغا تبعيات
المستوى: مبتدئ إلى متوسط
90-120 دقيقة

الخطوة 1 — التحقق من Git وتحضير مجلد التثبيت

git --version

يجب رؤية رقم إصدار ≥ 2.40. إن أرجع «command not found»، ثبّت Git أولاً.

القاعدة الذهبية للمسار: لا فراغات، لا حروف خاصة، لا امتيازات مرتفعة. C:\src\flutter على Windows أو ~/development/flutter على macOS/Linux. تجنّب C:\Program Files، OneDrive، iCloud.

# Linux / macOS
mkdir -p ~/development

# Windows PowerShell
New-Item -ItemType Directory -Force -Path C:\src

الخطوة 2 — تنزيل واستخراج Flutter SDK

اذهب إلى docs.flutter.dev/install واختر نظامك. وقت الكتابة، القناة المستقرّة تقترح Flutter 3.41 مع Dart 3.11. نزّل الأرشيف (≈ 1.2 جيغا على Windows، ≈ 800 ميغا على macOS، ≈ 700 ميغا على Linux).

# Windows PowerShell
Expand-Archive -Path $env:USERPROFILE\Downloads\flutter_windows_3.41.X-stable.zip -DestinationPath C:\src

# macOS
unzip ~/Downloads/flutter_macos_3.41.X-stable.zip -d ~/development/

# Linux
tar -xf ~/Downloads/flutter_linux_3.41.X-stable.tar.xz -C ~/development/

الاستخراج يأخذ دقائق — إنه repo Git كامل بمئات آلاف الملفات. تحقّق:

ls ~/development/flutter/bin    # Linux/macOS
dir C:\src\flutter\bin          # Windows

يجب رؤية flutter، flutter.bat، dart، dart.bat.

الخطوة 3 — إضافة Flutter إلى PATH

على Windows، افتح «تعديل متغيّرات بيئة حسابك». في «متغيّرات المستخدم»، اختر Path، عدّل، جديد، وألصق C:\src\flutter\bin.

على macOS (zsh منذ Catalina):

echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

على Linux:

# Bash
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zshenv
source ~/.zshenv

# Fish
fish_add_path -g -p ~/development/flutter/bin

flutter --version

يجب رؤية إصدار Flutter (3.41)، framework، engine، Dart، DevTools، والقناة stable.

الخطوة 4 — تثبيت Android Studio وSDK Android

نزّل Android Studio من developer.android.com/studio وثبّت بالخيارات الافتراضية. عند الإطلاق الأول، اقبل تثبيت SDK Android. اختر Standard.

افتح SDK Manager. في تبويب SDK Platforms، اختر Android 15 (API level 35) — الحد الأدنى المطلوب من Google Play منذ 31 أغسطس 2025. إن توفّر Android 16 (API 36)، اختره أيضاً.

في تبويب SDK Tools، تأكّد من تثبيت:

Android SDK Build-Tools
Android SDK Command-line Tools (latest)
Android Emulator
Android SDK Platform-Tools

الخطوة 5 — قبول licenses Android

flutter doctor --android-licenses

السكربت يعرض كل license وينتظر مصادقتك. اكتب y للقبول، حتى رسالة «All SDK package licenses accepted». خطوة إلزامية وغير قابلة للعودة.

إن لم تجد الأداة SDK Android، اضبط متغيّر البيئة ANDROID_HOME:

~/Library/Android/sdk (macOS)
~/Android/Sdk (Linux)
%LOCALAPPDATA%\Android\Sdk (Windows)

الخطوة 6 — تثبيت VS Code والإضافة Flutter

Android Studio يكفي للتطوير، لكن كثيرون يفضّلون VS Code لخفته. نزّل من code.visualstudio.com، ثبّت، ثم أضف امتدادين:

Flutter (publisher Dart-Code.flutter) — تكامل كامل: أوامر، hot reload، تشغيل emulator، debug.
Dart — تُثبَّت تلقائياً كتبعية من Flutter.

الخطوة 7 — تشغيل flutter doctor وتصحيح التحذيرات

flutter doctor -v

راية -v تعطي التفصيل الكامل. مخرَج سليم:

[✓] Flutter (Channel stable, 3.41.X, on ...)
[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.0)
[✓] Android Studio (version 2025.1)
[✓] VS Code (version 1.96.x)
[✓] Connected device (1 available)
[✓] Network resources

• No issues found!

إن كان مربّع أحمر أو برتقالي، اقرأ الرسالة باعتناء — Flutter يدلّ غالباً على الأمر الدقيق للحلّ. الكلاسيكيات: licenses غير مقبولة، cmdline-tools مفقودة، JDK قديم (Android Studio منذ Ladybug في أكتوبر 2024 يحمل JDK 21 الخاص به؛ لا تثقل JAVA_HOME دون سبب).

الخطوة 8 — إنشاء أول مشروع وتشغيل emulator Android

cd ~/development
flutter create hello_flutter
cd hello_flutter

Flutter يولّد مشروعاً كاملاً: lib/main.dart نقطة الدخول Dart، android/ وios/ wrappers أصلية، pubspec.yaml يعلن التبعيات.

من Android Studio، افتح Device Manager وأنشئ Pixel 7 API 35. حالما الـ emulator يشتغل:

flutter devices
flutter run

التصريف الأول يأخذ دقيقة إلى دقيقتين. التطبيق يظهر في الـ emulator. عدّل العنوان الافتراضي 'Flutter Demo Home Page' في lib/main.dart، احفظ، ولاحظ hot reload: تغييرك يظهر في أقل من 500 مللي ثانية بلا إعادة تشغيل.

أخطاء شائعة

الخطأ	السبب	الحل
`flutter: command not found`	PATH لم يُعَد تحميله	افتح terminal جديد. `echo $PATH`
«You have not accepted the license agreements»	licenses Android SDK	أعد `flutter doctor --android-licenses`
«Unable to locate Android SDK»	`ANDROID_HOME` غائب	صدّر `ANDROID_HOME` نحو مسار SDK
Hot reload لا يشتغل	تعديل widget `const` أو تغيير `main()`	استخدم `r` في طرفية `flutter run`، `R` لـ hot restart
emulator بطيء جداً	تسارع عتاد معطّل (HAXM/Hyper-V/KVM)	فعّل المحاكاة في BIOS. على Linux `qemu-kvm`
Build Gradle يفشل	JDK غير متوافق	عطّل `JAVA_HOME` إن ثبّت JDK منفصلاً

أسئلة شائعة

هل أحتاج Xcode لـ Flutter على Mac؟ فقط إن استهدفت iOS. للـ Android، Command Line Tools (xcode-select --install) تكفي.

أي JDK؟ Android Studio يحمل JDK خاصه: 17 LTS حتى Koala، 21 LTS منذ Ladybug. لا تستبدل عبر JAVA_HOME.

Flutter بلا Android Studio؟ نعم، بتثبيت يدوي cmdline-tools وSDK عبر sdkmanager. أخفّ لكن أعقد.

Flutter لـ iOS بلا Mac؟ الكتابة والتصريف ممكنان على Windows/Linux، لكن build وتوقيع iOS النهائيان يتطلبان macOS وXcode. Codemagic أو GitHub Actions بـ runner macOS يلتفّان حول الحاجة لـ Mac فيزيائي.

كيف نحدّث Flutter؟ flutter upgrade يستلم آخر إصدار من قناة stable. fvm (Flutter Version Manager) يسمح بإدارة عدة SDK متوازية.

تثبيت Flutter SDK وضبط بيئة التطوير