Eski Sürümlü Flutter Projesini Yeni Sürüme Güncelleme

7 min readMar 26, 2025

Merhaba değerli okurlar, bugün sizlere Eski sürümlü flutter projesini yeni sürüme güncellerken karşımıza çıkan hataları nasıl çözebileceğimizi anlatmaya çalışacağım.

Flutter ve Dart SDK kullanarak uzun zaman önce yazdığımız projeler olabiliyor ya da open source olarak bulduğumuz projeler uzun zamandır güncelleme almadığı için kullanamıyoruz. İşte bu sorunları çözmek için sizlere elimden geldiğince bir rehber hazırlamaya çalışacağım.

Önemli Not: Bu işlemlere başlamadan önce projenizin mutlaka bir yedeğini alın! Git gibi bir versiyon kontrol sistemi kullanıyorsanız, tüm değişikliklerinizi commit’lediğinizden emin olun. Bu, herhangi bir sorunla karşılaştığınızda kolayca geri dönebilmenizi sağlar.

Eğer farklı projelerde farklı Flutter sürümleriyle çalışmanız gerekiyorsa veya bu güncelleme süreci size karmaşık geliyorsa, Flutter Sürüm Yönetimi aracı olan FVM (Flutter Version Management) konusunu araştırmayı düşünebilirsiniz. FVM, projenize özel Flutter SDK sürümleri tanımlamanıza ve bunlar arasında kolayca geçiş yapmanıza olanak tanıyarak farklı projeler arasındaki sürüm çakışmalarını önler.

Şimdi adım adım ilerleyerek işlemlere başlayalım..

1- Eski Flutter Sürümünü ve Paketleri Güncelleme

Flutter Ortamı Kontrolü: Terminalde aşağıdaki komutu çalıştırarak Flutter kurulumunuzun, bağlı geliştirme araçlarının (Android Studio, Xcode, VS Code vb.) ve diğer bağımlılıkların sağlıklı ve güncel olduğundan emin olun:

flutter doctor -v

Eğer herhangi bir sorun yoksa bu adımdan sonra yapacağımız ilk iş projenin Flutter ve paketlerin sürümlerini güncellemek olmalı.

# İsteğe bağlı: Stabil kanalda olduğunuzdan emin olmak için
# flutter channel stable 

# Flutter SDK'sını mevcut kanaldaki en son sürüme yükseltir

flutter upgrade

flutter pub get

Yukarıdaki kodlarla Flutter sürümünü yükseltiyor ve bağımlılıkları yüklüyoruz.
Daha sonra aşağıdaki kod ile güncel olmayan paketleri kontrol ediyoruz.

flutter pub outdated

Güncel olmayan paketleri saptadıktan sonra bu paketleri Flutter sürümümüzle uyumlu şekilde güncellemek adına aşağıdaki kodu kullanıyor olacağız.

flutter pub upgrade — major-versions

Burada aklınıza neden pub upgrade komutunu direkt olarak kullanmayıp major-versions eklediğimiz sorusu gelebilir.

Neden — major-versions? Standart flutter pub upgrade, pubspec.yaml içindeki sürüm kısıtlamalarına uyar (örn: http: ^1.0.0 sadece 1.x.x sürümlerine güncellenir, 2.0.0'a geçmez). — major-versions bayrağı ise bu kısıtlamaları göz ardı ederek paketleri mevcut en son kararlı ana sürümlerine (örn: http: ^2.0.0) yükseltmeye çalışır.
Dikkat: Kırılma Değişiklikleri (Breaking Changes): Bu komut, paketlerin API’larında geriye dönük uyumlu olmayan değişiklikler (breaking changes) içerebilen yeni ana sürümlere geçiş yapabilir. Bu nedenle, bu adımdan sonra kodunuzda derleme hataları almanız oldukça muhtemeldir. Bu hataları sonraki adımlarda, özellikle “Widget ve Kod Hataları” bölümünde ele alacağız. Güncellenen paketlerin CHANGELOG.md dosyalarını veya pub.dev sayfalarını kontrol etmek, bu değişiklikleri anlamanıza yardımcı olacaktır.

Gradle Sorunlarını Giderme (Android)

Gradle sorunları zaman zaman insanı projeden soğutuyor dersem abartmış olmam diye düşünüyorum =) Çoğu zaman karmaşık hatalar veren bu yapıyıda adım adım giderek düzeltmeye çalışacağız..

Android Gradle Plugin (AGP) Sürümünü Güncelleme: Flutter sürümünüz yükseldiği için, muhtemelen daha yeni bir Android Gradle Plugin sürümüne ihtiyacınız olacaktır.
android/build.gradle dosyasını açın ve dependencies bloğu içindeki classpath satırını güncelleyin. En güncel ve projenize uygun sürümü bulmak için Android Gradle Plugin Sürüm Notları sayfasına bakabilirsiniz. Bu sayfa, hangi AGP sürümünün hangi Gradle sürümüyle uyumlu olduğunu da gösterir.

classpath “com.android.tools.build:gradle:7.4.2”

Not: Yukarıdaki 7.4.2 sadece bir örnektir, projeniz ve Flutter sürümünüz için uygun olan en güncel stabil sürümü kullanın.

Gradle Wrapper Sürümünü Güncelleme:

Bu adımdan sonra AGP sürümüyle uyumlu Gradle sürümünü kullanmanız gerekir. android/gradle/wrapper/gradle-wrapper.properties dosyasını açın ve distributionUrl satırını, seçtiğiniz AGP sürümüyle uyumlu olan Gradle sürümüyle güncelleyin (yukarıda belirtilen linkten kontrol edebilirsiniz).

distributionUrl=https\://services.gradle.org/distributions/gradle-7.6.3-all.zip

Kotlin Sürümünü Kontrol Etme:
android/build.gradle dosyasında tanımlanan ext.kotlin_version değerinin de kullandığınız AGP ve diğer bağımlılıklarla uyumlu olması gerekebilir. Genellikle AGP sürüm notlarında önerilen Kotlin sürümleri belirtilir.


buildscript {
 ext.kotlin_version = ‘1.8.10’
}

Bu değişikliklerden sonra Sonra Gradle’ı temizleyip yeniden derledim:

cd android
./gradlew clean
./gradlew build

Bu adımdan sonra Flutter projenizi IDE üzerinden aşağıdaki kod ile çalıştırmayı deneyin

flutter run

//daha detaylı çıktı görmek için verbose kullanabilirsiniz

//flutter run --verbose

Gradle Hatalarını Ayıklama:
Hata alırsanız, hata mesajlarını dikkatlice okumaya çalışın. Hata mesajlarında hangi paket ya da yapılandırmanın hata verdiğini yakalayabilirsiniz. Genel olarak görebileceğiniz hatalardan bazıları şu şekilde olacaktır;
Dependency Conflicts (Bağımlılık Çakışmaları): Farklı paketlerin aynı kütüphanenin uyumsuz sürümlerini gerektirmesi. Hata mesajları genellikle çözüm önerileri sunar.
Deprecated API Usage (Eski API Kullanımı): Kullandığınız bir paketin veya kodun, güncel Android sürümlerinde kaldırılmış veya değiştirilmiş bir API’yi kullanması.
Syntax Errors (Sözdizimi Hataları): build.gradle dosyalarındaki yazım hataları.
Minimum SDK Uyumsuzluğu: Bazı paketlerin projenizin minSdkVersion değerinden daha yüksek bir sürüm gerektirmesi (android/app/build.gradle dosyasında minSdkVersion ayarını kontrol edin).
İnternette hata mesajını aratarak veya Stack Overflow gibi platformlarda benzer sorunlara yönelik çözümleri araştırarak ilerleyebilirsiniz.

Java Sürüm Sorunları (Android)

Başımızı ağrıtan bir diğer sorunda Java sürüm sorunları. Ya çok yüksek ya da çok düşük java sürümü kullandığımızdan dolayı genelde hata verir.
Java versiyonumuzun 17 olması gerekiyor.

Ben MacOs işletim sistemine sahip bilgisayar kullandığım için ona göre bir anlatım yapacağım.

Ben homebrew üzerinden java 17 kuracağım

brew install openjdk@17

Java yüklendi şimdi Javanın varsayılan olarak 17 sürümünü kullanmasını sağlayalım. Aşağıdaki kodu terminale yazın

export JAVA_HOME=$(/usr/libexec/java_home -v 17)

Bu yolu zshrc dosyamıza ekleyerek kalıcı hale getirelim.. Aşağıdaki koduda terminale yazalım.

echo ‘export JAVA_HOME=$(/usr/libexec/java_home -v 17)’ >> ~/.zshrc 

source ~/.zshrc

Bu işlemlerden sonra java versiyonumuzu kontrol etmek için yine terminale java -version yazarak sürüm kontrolümüzü yapalım.

Diğer İşletim Sistemleri:

Windows: Oracle JDK veya OpenJDK indirip kurun. Ardından “Ortam Değişkenleri” ayarlarından JAVA_HOME değişkenini JDK’nın kurulu olduğu dizine (örneğin C:\Program Files\Java\jdk-17) ayarlayın ve Path değişkenine %JAVA_HOME%\bin yolunu ekleyin.
Linux: Paket yöneticinizi veya SDKMAN gibi araçları kullanarak JDK 17'yi kurun ve JAVA_HOME ayarını yapın
Android Studio JDK Ayarı: Bazen sistem geneli yerine Android Studio’nun kendi Gradle derlemeleri için kullandığı JDK’yı ayarlamak gerekebilir. Android Studio’da File > Settings (veya Preferences) > Build, Execution, Deployment > Build Tools > Gradle altında “Gradle JDK” ayarını kontrol edin ve JDK 17'yi seçin.

Widget ve Kod Hatalarını Düzeltme (Refactoring)

Flutter SDK’sını ve paketleri — major-versions ile güncellediyseniz, kod tabanınızda derleme hatalarıyla karşılaşmanız oldukça olasıdır. Bunun nedeni, Flutter’ın veya güncellenen paketlerin API’larında yapılan “breaking changes” (kırılma değişiklikleri)dir. Artık bu hataları gidermek için kodunuzu düzenlemeniz (refactor) gerekecek. Refactor işlemleri için lütfen sabırlı olun. Özellikle yapay zeka ve paketlerin ilgili sayfalarından aldığınız bilgilerle ilerlemeye özen gösterin.

Yaygın Değişiklik Örnekleri:

Button Widget’ları: Eski RaisedButton, FlatButton, OutlineButton widget’ları kaldırıldı. Yerlerine ElevatedButton, TextButton, OutlinedButton kullanmanız gerekir. Stil özellikleri de style parametresi üzerinden (ElevatedButton.styleFrom, TextButton.styleFrom vb.) ayarlanır.
Tema (ThemeData): Tema yapısında ve renk tanımlamalarında (ColorScheme) değişiklikler olabilir. Eski kullanımlar uyarı veya hata verebilir.
Null Safety: Eğer projeniz null safety öncesi (Flutter < 2.0, Dart < 2.12) bir sürümden geliyorsa, kodunuzu null safety uyumlu hale getirmeniz gerekir. Bu, değişkenlere, parametrelere ve dönüş tiplerine ?, ! gibi null safety operatörlerini eklemeyi veya required anahtar kelimesini kullanmayı içerir. dart migrate aracı yardımcı olsa da, manuel düzenlemeler genellikle şarttır.
Paket API Değişiklikleri: Güncellediğiniz her paketin kendi API’larında değişiklikler olabilir. Örneğin, bir paketin fonksiyon adı değişmiş, parametreleri farklılaşmış veya bazı sınıflar yeniden adlandırılmış olabilir.

Çözüm Yolları:

IDE Analiz ve Hızlı Düzeltmeler: Android Studio veya VS Code gibi IDE’ler, koddaki hataları ve uyarıları gösterir. Genellikle altı çizili kodun üzerine gelerek veya Alt+Enter (veya Option+Enter) tuşlarına basarak önerilen hızlı düzeltmeleri (quick fixes) görebilir ve uygulayabilirsiniz. Bu, özellikle basit API değişikliklerini düzeltmede çok etkilidir.
Flutter ve Dart Yayın Notları: Büyük Flutter ve Dart sürümlerinin yayın notlarında (release notes) “Breaking Changes” başlığı altında önemli değişiklikler listelenir. Bunları incelemek, karşılaştığınız hataların nedenini anlamanıza yardımcı olur.
Paket Dökümantasyonu ve CHANGELOG: Güncellediğiniz her paketin pub.dev sayfasındaki dökümantasyonunu, örneklerini ve özellikle CHANGELOG.md dosyasını inceleyin. CHANGELOG dosyası, sürümler arasındaki tüm değişiklikleri (özellikle kırılma değişikliklerini) listeler.
Yapay Zeka Yardımı: Hata mesajlarını veya sorunlu kod bloklarını ChatGPT gibi yapay zeka modellerine sorarak çözüm önerileri veya açıklama alabilirsiniz.

Bu aşama sabır gerektirir. Hataları tek tek ele almaya ve nedenini anlamaya çalışın. Tekrar belirtmiş olayım bu aşamada yapay zekadan faydalanmanızı ve sorun çıkaran paketlerin güncel kullanım senaryolarını araştırmanızı tavsiye ederim

iOS RunnerTests Sorunu

Muhtemelen bir çoğumuzun karşılaştığı bir sorundur. Xcode güncellemesinden sonra böyle bir hata aldığımı hatırlıyorum. Bu sorunu çözmek için ios klasöründe bulunan Podfile (ios/Podfile) dosyasını açıyoruz ve aşağıdaki kod bloğunu yorum satırı haline getirerek bu hatayı ekarte ediyoruz.

# platform :ios, '11.0' # Veya sizin platform sürümünüz

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

# Aşağıdaki bloğu yorum satırı yapın
# target 'RunnerTests' do
#   inherit! :search_paths
#   # Pods for testing
# end

Bu işlemden sonra Podfile dosyasındaki değişikliği diğer yapıya aktarabilmek adına aşağıdaki kodları projemizin olduğu yerde açacağımız terminale yapıştırıyoruz

cd ios
pod deintegrate # CocoaPods’u projeden tamamen kaldırır
rm -rf Pods Podfile.lock # Eski Pods klasörünü ve lock dosyasını siler
pod install — verbose # Bağımlılıkları ayrıntılı modda yeniden yükler
cd ..

CocoaPods Sürümü Güncelleme

Bir diğer sorunumuz CocoaPods’un sürümünün düşük kalması olacaktır.
Terminali açıp aşağıdaki kodu çalıştırarak cocoapods sürümümüzü güncelliyor olacağız.

sudo gem install cocoapods # En son CocoaPods sürümünü yükler
pod repo update # Yerel CocoaPods depo listesini günceller

Bu işlemden sonra dilerseniz her şeyin en temizden tekrar oluşturulması adına aşağıdaki kodlarıda projenizin ios klasöründe çalıştırabilirsiniz..

cd ios
# pod deintegrate ve rm -rf Pods Podfile.lock (gerekirse tekrar çalıştırılabilir)
pod install — verbose
cd ..

Evet iOS tarafı için alabileceğimiz hatalarıda bu şekilde çözüyor olduk.

Son Çare: Android ve iOS Klasörlerini Yeniden Oluşturma

Eğer yukarıdaki tüm adımları denemenize rağmen çözülemeyen, karmaşık platforma özgü hatalar alıyorsanız ve projeniz derlenemiyorsa, son çare olarak Flutter’ın projeniz için android ve ios platform klasörlerini sıfırdan oluşturmasını sağlayabilirsiniz.

!!! UYARI: BU İŞLEM GERİ ALINAMAZ VE TÜM PLATFORMA ÖZGÜ YAPILANDIRMALARINIZI SIFIRLAR !!!

Bu yönteme başvurmadan önce sonuçlarını anladığınızdan emin olun. Aşağıdakiler dahil ancak bunlarla sınırlı olmamak üzere birçok yapılandırmayı kaybedeceksiniz:

android/app/build.gradle dosyasındaki özel ayarlar (uygulama kimliği, sürüm kodu/adı mantığı, imzalama yapılandırmaları, bağımlılıklar).
AndroidManifest.xml dosyasındaki izinler, activity/service/receiver tanımları, meta-data etiketleri, intent filtreleri.
ios/Runner/Info.plist dosyasındaki izin kullanım açıklamaları (privacy keys), URL şemaları, build/version numaraları, özel anahtarlar.
ios/Podfile dosyasındaki özel pod ayarları, platform sürümü, post-install betikleri.
Firebase kurulum dosyaları (google-services.json, GoogleService-Info.plist).
Uygulama imzalama anahtarları ve yapılandırmaları (keystore dosyaları, provisioning profilleri).
Eklediğiniz tüm özel native Java/Kotlin/Objective-C/Swift kodları veya kütüphaneler.

Eğer devam etmeye kararlıysanız:

MUTLAKA KAPSAMLI YEDEK ALIN: Mevcut android ve ios klasörlerinizin tamamını proje dışı güvenli bir yere kopyalayın. Özellikle yukarıda listelenen yapılandırma dosyalarını ve özel kodlarınızı içeren her şeyi yedeklediğinizden emin olun.

2. Klasörleri Silin: Projenizin ana dizinindeki android ve ios klasörlerini silin.

Platform Klasörlerini Yeniden Oluşturun: Projenizin ana dizininde terminali açın ve şu komutu çalıştırın:

flutter create .

Bu komut, mevcut Flutter SDK sürümünüze uygun, varsayılan ayarlarla temiz android ve ios klasörlerini oluşturacaktır.

Yapılandırmaları Dikkatlice Geri Aktarın: Şimdi en zahmetli kısım başlıyor. Yedeklediğiniz eski android ve ios klasörlerindeki gerekli yapılandırmaları (izinler, anahtarlar, build.gradle ayarları, Info.plist girdileri, Firebase dosyaları, imzalama ayarları vb.) yeni oluşturulan klasörlerdeki ilgili dosyalara tek tek ve dikkatlice manuel olarak yeniden eklemeniz gerekecektir. Özel native kodlarınızı da yeni yapıya uygun şekilde entegre etmelisiniz.

Bu yöntem, temiz bir temel sağlasa da, önceki tüm platforma özgü özelleştirmelerinizi kaybetmenize neden olur ve bunları hatasız bir şekilde yeniden uygulamak ciddi zaman ve dikkat gerektirir. Bu nedenle, yalnızca diğer tüm yöntemler başarısız olduğunda ve projenin karmaşıklığı bu riski almayı haklı çıkardığında düşünülmelidir.

Umarım bu yazımda ilgilisi için faydalı olur. Bir sonraki yazıda görüşmek üzere…

Github: www.github.com/abdullah017
Linkedin: www.linkedin.com/in/abdullahtas
Stackoverflow: https://stackoverflow.com/users/13807726/abdullah-t