Flutter ile geliştirilen Android uygulamalarının test edilmesi veya mağaza dışı dağıtılması için APK dosyasının oluşturulması gerekmektedir. Google Play Store tarafında Android App Bundle (AAB) formatı tercih edilse de, APK hâlâ test, kurum içi dağıtım ve manuel kurulum senaryolarında yaygın biçimde kullanılmaktadır. Bu rehberde, bir Flutter projesi için debug ve release APK oluşturma süreci, imzalama adımlarıyla birlikte adım adım açıklanmaktadır. Böylece hem geliştirme ortamında hem de son kullanıcı tarafında kullanılabilecek APK dosyaları üretilebilmektedir.

Gerekenler listesi

• Kurulu ve güncel Flutter SDK
• Kurulu Android Studio veya Android SDK bileşenleri
• flutter doctor çıktısında kritik hata bulunmayan bir geliştirme ortamı
• Mevcut bir Flutter projesi
• Release APK için:
  • Keystore (JKS) dosyası
  • Keystore parolası, alias ve imzalama bilgileri

Adım adım nasıl yapılır?

Adım 1: Geliştirme ortamının kontrol edilmesi

• Terminal veya komut satırı açılır.
• Aşağıdaki komut çalıştırılır:
  flutter doctor
• Eksik Android SDK, lisans veya ortam bileşenleri varsa komut satırında belirtilen yönlendirmelere göre tamamlanır.
• Kritik bileşenler çözüldükten sonra APK oluşturma işlemine geçilir.

Adım 2: Proje dizinine geçilmesi

• Terminalde Flutter projesinin kök dizinine geçilir:
  cd proje_klasoru
• pubspec.yaml dosyasının ve lib klasörünün bulunduğu dizinde olunduğundan emin olunur.
• Gerekirse bağımlılıkların güncellenmesi için:
  flutter pub get
  komutu çalıştırılır.

Adım 3: Debug APK oluşturulması

• Geliştirme ve hızlı testler için debug APK oluşturmak amacıyla şu komut kullanılır:
  flutter build apk
• Varsayılan olarak debug modunda bir APK üretimi gerçekleştirilir.
• Oluşan dosya genellikle şu yolda bulunur:
  build/app/outputs/flutter-apk/app-debug.apk
• Bu APK, USB kablo veya dosya paylaşımı yoluyla Android cihaza aktarılıp kurulabilir.

Adım 4: Release APK için keystore oluşturulması

• Release (dağıtıma uygun) APK üretmek için imzalı bir keystore dosyası gereklidir.
• Java keytool aracı kullanılarak yeni bir keystore oluşturulabilir. Örnek komut:

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-key-alias

• Oluşturulan .jks dosyası, genellikle android/app klasörü altına veya güvenli bir dizine yerleştirilir.
• Keystore parolası ve alias bilgileri güvenli biçimde saklanmalıdır.

Adım 5: key.properties dosyasının hazırlanması

• Flutter projesi içindeki android klasöründe key.properties adında bir dosya oluşturulur.
• Aşağıdaki örnek yapı ilgili dosyaya eklenir:

storePassword=KESTORE_SIFRESI
keyPassword=KEY_SIFRESI
keyAlias=my-key-alias
storeFile=../app/my-release-key.jks

• storeFile yolunun, keystore dosyasının gerçek konumuna uygun olduğundan emin olunur.

Adım 6: Gradle imzalama yapılandırmasının yapılması

• android/app/build.gradle dosyası açılır.
• Dosyanın üst kısmında key.properties dosyasını okuyan kod bloğu eklenir:

def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file('key.properties')
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

• Ardından android { ... } bloğu içinde signingConfigs ve buildTypes ayarları şu şekilde yapılandırılır:

signingConfigs {
    release {
        storeFile file(keystoreProperties['storeFile'])
        storePassword keystoreProperties['storePassword']
        keyAlias keystoreProperties['keyAlias']
        keyPassword keystoreProperties['keyPassword']
    }
}

buildTypes {
    release {
        signingConfig signingConfigs.release
        minifyEnabled false
        shrinkResources false
    }
}

• Değişiklikler kaydedilir ve Gradle senkronizasyonunun başarılı olduğundan emin olunur.

Adım 7: Release APK oluşturulması

• Projenin kök dizinine dönülür.
• Aşağıdaki komut ile release APK oluşturulur:
  flutter build apk --release
• İşlem tamamlandığında imzalı release APK genellikle şu dizinde bulunur:
  build/app/outputs/flutter-apk/app-release.apk
• Bu dosya, mağaza dışı son kullanıcı dağıtımı veya kurum içi dağıtım için kullanılabilir.

Adım 8: Mimarilere göre ayrılmış APK üretimi (isteğe bağlı)

• Daha küçük dosya boyutu için mimari bazlı APK üretmek amacıyla şu komut kullanılabilir:
  flutter build apk --split-per-abi
• Bu komut sonucunda armeabi-v7a, arm64-v8a gibi farklı cihaz mimarileri için ayrı APK dosyaları oluşur.
• Bu yöntem, özellikle depolama alanı kısıtlı cihazlarda avantaj sağlamaktadır.

İpuçları ve sık yapılan hatalar

• Keystore dosyası ve key.properties içeriği, sürüm kontrol sistemlerine eklenmemeli ve gizli tutulmalıdır.
• Debug APK ile release APK arasında performans ve davranış farkları olabileceği için yayın öncesi testlerin release APK üzerinden yapılması önemlidir.
• build.gradle dosyasında yapılan küçük yazım hataları derleme sürecinin tamamen başarısız olmasına yol açabilir; hata mesajları dikkatle incelenmelidir.
• Derleme sorunları yaşandığında flutter clean komutu bazı durumlarda çözüm sağlayabilir; ardından flutter pub get ve build komutları yeniden çalıştırılmalıdır.
• Gereksiz paketler ve kullanılmayan görsel veya kaynak dosyaları, APK boyutunu artıracağı için projeden temizlenmelidir.

Editör notu

Flutter ile APK oluşturma süreci doğru yapılandırıldığında, hem geliştirme hem de dağıtım senaryolarında tekrar edilebilir ve güvenilir bir akış sağlamaktadır. Geliştirme ortamı, keystore yönetimi ve Gradle ayarları düzenli tutulduğunda debug ve release APK üretimi, projelerin standart bir parçası hâline gelmektedir.