Bu rehberde Flutter’ı macOS üzerinde sıfırdan kuracağız: Flutter SDK indirme, PATH ayarı, Xcode + iOS Simulator hazırlığı, CocoaPods kurulumu, Android Studio ve VS Code eklentileri… En sonda da “flutter doctor” ile her şeyi kontrol edeceğiz.
İçindekiler
- Ön koşullar
- Mac çipini kontrol et (Apple Silicon / Intel)
- Flutter SDK indir ve kur
- Flutter’ı PATH’e ekle (zsh)
- Kurulumu doğrula: flutter doctor
- Xcode ve iOS Simulator kurulumu
- CocoaPods kurulumu (iOS için)
- Android Studio kurulumu + SDK Tools
- Android lisanslarını kabul et
- VS Code + Flutter eklentisi
- Pro Tip: Projeyi doğru başlat (—org)
- Sık sorulan sorular
- Hata Kodları ve Çözümleri
1) Ön koşullar
- macOS (mümkünse güncel)
- Stabil internet bağlantısı
- Terminal kullanımı (kopyala-yapıştır seviyesinde yeterli)
- iOS hedefliyorsan: Xcode
- Android hedefliyorsan: Android Studio
2) Mac çipini kontrol et (Apple Silicon / Intel)
Flutter SDK indirirken doğru paketi seçmek için Mac’in işlemci tipini bilmek şart. En kolay yol: Apple menüsü > “About This Mac” ekranındaki “Chip” alanına bakmak.
Apple Silicon (M1/M2/M3/…) kullanıyorsan bazı bileşenlerde Rosetta gerekebilir. Aşağıdaki komutla Rosetta 2 kurulumu yapılır:
sudo softwareupdate --install-rosetta --agree-to-license3) Flutter SDK indir ve kur
Flutter’ı kurmanın en temiz yolu resmi SDK paketini indirip belirli bir klasöre çıkarmaktır. İndirirken işlemcine uygun (Intel / Apple Silicon) paketi seç.
3.1) Kurulum klasörü oluştur
Örnek olarak ~/Development altında bir yapı kullanacağız:
mkdir -p ~/Development3.2) SDK’yı klasöre çıkar
İndirdiğin dosya genelde “Downloads” klasöründedir. Dosya adın farklıysa yıldız (*) kalıbı işini görür:
unzip ~/Downloads/flutter_macos_*.zip -d ~/Development/Kurulum tamamlanınca Flutter dizini genelde şuna benzer: ~/Development/flutter
4) Flutter’ı PATH’e ekle (zsh)
macOS’ta varsayılan shell çoğunlukla zsh’dır. Kontrol etmek için:
dscl . -read ~/ UserShellÇıktıda /bin/zsh görüyorsan harika.
4.1) .zshenv dosyasını düzenle
PATH eklemesini ~/.zshenv dosyasına yapmak pratik bir yöntemdir:
Aşağıdaki satırı dosyanın en altına ekle:
export PATH=$HOME/Development/flutter/bin:$PATHKaydedip terminali kapat-aç. Alternatif olarak şu komutla anında uygulayabilirsin:
source ~/.zshenv5) Kurulumu doğrula: flutter doctor
Flutter kurulumunda “her şey tamam mı?” sorusunun cevabı flutter doctor. Bu komut eksikleri tek tek listeler.
flutter doctorİlk aşamada “Xcode missing” veya “Android toolchain missing” gibi uyarılar görmen normal. Bir sonraki adımlarda onları kapatacağız.
6) Xcode ve iOS Simulator kurulumu
iPhone/iPad hedefliyorsan Xcode şart. App Store’dan Xcode’u kurduktan sonra: Xcode ayarlarında “Command Line Tools” seçili olduğundan emin ol (Locations sekmesi).
Sonrasında tekrar kontrol:
flutter doctor7) CocoaPods kurulumu (iOS için)
iOS tarafında birçok Flutter paketinin native bağımlılıkları CocoaPods üzerinden yönetilir. Kurulum için en yaygın yöntem:
sudo gem install cocoapodsEğer Ruby sürümü/ortamı yüzünden “Error installing cocoapods” gibi bir hata alırsan, genelde en sorunsuz çözüm Homebrew ile güncel Ruby kurup ardından CocoaPods’u kurmaktır.
7.1) Homebrew kurulumu
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"7.2) Ruby kurulumu (Homebrew)
brew install rubyArdından Ruby PATH eklemesi (örnek):
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrcSon olarak CocoaPods (brew ile):
brew install cocoapodsKontrol:
flutter doctorMini şaka: CocoaPods bağımlılık eklemeyi sevdiği kadar kimseyi sevmez… 😄
8) Android Studio kurulumu + SDK Tools
Android hedefliyorsan Android Studio kurup SDK bileşenlerini tamamlaman gerekir. Android Studio içinde SDK Tools kısmından “Android SDK Command-line Tools (latest)” seçili olmalı.
9) Android lisanslarını kabul et
Android araç zinciri tamamlandıktan sonra lisansları kabul etmezsen Flutter “doctor” uyarı bırakır. Şu komutla lisansları onayla:
flutter doctor --android-licensesTekrar kontrol:
flutter doctor10) VS Code + Flutter eklentisi
VS Code ile çalışacaksan Flutter ve Dart eklentilerini kur. Sonrasında proje açınca debug/run akışı çok daha keyifli hale geliyor.
11) Pro Tip: Projeyi doğru başlat (—org)
Uygulamanı yayınlamayı düşünüyorsan proje oluştururken --org kullanmak büyük rahatlık sağlar. Bu sayede Android applicationId ve iOS bundle identifier daha en baştan düzgün ayarlanır.
flutter create --org com.seninalanadinin ters hali proje_adiÖrnek: domain’in example.com ise genelde com.example şeklinde kullanılır. (Gerçek uygulama yayınında ileride vakit kazandırır.)
12) Sık Sorulan Sorular (SSS)
Flutter komutu “command not found” diyor, neden?
Büyük ihtimalle PATH satırı doğru dosyada değil ya da terminal yeniden başlatılmadı. ~/.zshenv içine eklediğin PATH satırını kontrol et ve terminali kapat-aç.
“flutter doctor” hâlâ Xcode eksik diyor
Xcode kurulu olsa bile “Command Line Tools” seçimi yapılmamış olabilir. Xcode ayarlarından Locations sekmesini kontrol et.
CocoaPods kurarken hata alıyorum
Sistem Ruby sürümü eski/uyumsuz olabiliyor. Homebrew + güncel Ruby + CocoaPods (brew) yöntemi genelde daha az sorun çıkarır.
Hem iOS hem Android yapacaksam sıralama ne olmalı?
Önerilen sıra: Flutter SDK → PATH → flutter doctor → Xcode → CocoaPods → Android Studio → Android licenses → tekrar doctor.
Not: Bu içerik, Mac’te Flutter kurulum akışını pratik şekilde anlatır. Resmi belgeler ve araçlar zamanla güncellenebilir. En doğru kontrol noktası her zaman flutter doctor çıktısıdır.
Hata Kodları ve Çözümleri (En Sık 10 Sorun)
Aşağıdaki hatalar Mac’te Flutter kurulumunda en sık görülenlerdir. Çoğu durumda çözüm: doğru PATH, doğru Xcode ayarı, doğru Android SDK bileşenleri ve en önemlisi flutter doctor çıktısındaki eksikleri kapatmaktır.
1) zsh: command not found: flutter
Neden: Flutter PATH’e ekli değil veya terminal yeniden açılmadı.
Çözüm: ~/.zshenv (veya ~/.zshrc) içine şunu ekle:
export PATH=$HOME/Development/flutter/bin:$PATH
Sonra:
source ~/.zshenvflutter --version
2) Doctor found issues in 1 category. (Xcode eksik görünüyor)
Neden: Xcode kurulu değil veya Command Line Tools seçili değil.
Çözüm: Xcode kur → Xcode > Settings > Locations > Command Line Tools seç. Sonra:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developersudo xcodebuild -runFirstLaunchflutter doctor
3) Xcode license agreement not accepted
Neden: Xcode lisansı kabul edilmemiş.
Çözüm:
sudo xcodebuild -license
4) Could not find an option named "ios" / iOS device listelenmiyor
Neden: iOS platform bileşenleri ve/veya Simulator runtime eksik olabilir.
Çözüm:
xcodebuild -downloadPlatform iOSopen -a Simulatorflutter devices
5) CocoaPods not installed / pod: command not found
Neden: CocoaPods yüklü değil ya da PATH’te görünmüyor.
Çözüm: Önce deneyin:
sudo gem install cocoapodspod --version
Olmazsa (daha stabil):
brew install cocoapodspod --version
6) Failed to build iOS app / pod install hataları
Neden: iOS bağımlılıkları bozulmuş olabilir veya Pod cache sorunlu olabilir.
Çözüm: Proje klasöründe:
flutter cleanrm -rf ios/Pods ios/Podfile.lockcd iospod installcd ..flutter run -d ios
7) Android toolchain - develop for Android devices eksik
Neden: Android Studio yüklü ama SDK bileşenleri eksik (özellikle Command-line Tools).
Çözüm: Android Studio > Settings > Android SDK: SDK Platforms + SDK Tools kısmından gerekli bileşenleri kur (Command-line Tools dahil). Sonra:
flutter doctor
8) Some Android licenses not accepted
Neden: Android SDK lisansları onaylanmadı.
Çözüm:
flutter doctor --android-licenses
9) Waiting for another flutter command to release the startup lock
Neden: Bir Flutter işlemi kilitte kalmış olabilir.
Çözüm: Flutter/Dart süreçlerini kapat:
ps aux | grep flutter# ardından ilgili PID için:kill -9 PID
Sonra tekrar:
flutter doctor
10) Apple Silicon’da tool uyumsuzluğu / Rosetta ihtiyacı
Neden: Bazı araçlar hâlâ Rosetta ile daha stabil çalışabiliyor.
Çözüm:
sudo softwareupdate --install-rosetta --agree-to-license
