تحديث Gradle في Flutter يحتاج توافق Gradle Wrapper وAGP وJDK وKotlin. أوامر pub upgrade تحدّث حزم Dart ولا تحدّث هذه الأدوات تلقائيًا.
اعرف طبقات البناء
Flutter SDK يضم Dart، وحزم pub تُعرّف في pubspec، بينما بناء Android يعتمد Gradle Wrapper وAndroid Gradle Plugin وJDK وربما Kotlin Plugin. لكل طبقة إصدار وتوافق مختلفان. لا تعالج رسالة Gradle بتحديث جميع حزم Dart أو حذف pubspec.lock.
افحص قبل التغيير
احفظ العمل في Git وشغّل flutter doctor -v، ثم افحص ./gradlew –version من مجلد android على macOS أو Linux. على Windows استخدم gradlew.bat. حدّد موضع تعريف AGP وKotlin في مشروعك: قد يكون Plugin DSL داخل settings أو version catalog، وقد يكون أسلوبًا قديمًا داخل buildscript.
اختر مجموعة متوافقة
ارجع لجدول توافق Gradle وAGP ومتطلبات JDK، ثم لدليل ترقية Flutter والمكتبات المستخدمة. لا تنسخ رقمًا أحدث لمجرد أنه الأحدث. إن احتجت الانتقال من apply القديم إلى plugins فاتبع دليل Flutter الخاص بالهجرة بدل خلط الطريقتين في الملفات.
نفذ الترقية على مراحل
غيّر مجموعة متوافقة في فرع منفصل، ثم جرّب التحليل والاختبارات وبناء Debug وRelease. راجع أول خطأ حقيقي؛ الكاش ليس سبب كل فشل. احتفظ بسجل النسخ والفرق حتى تستطيع الرجوع، ولا تنشر تحديثًا قبل اختبار التوقيع والخدمات الأصلية على جهاز فعلي.
مثال للتطبيق
flutter doctor -v
# من مجلد android على macOS أو Linux:
./gradlew --version
# بعد اختيار النسخ المتوافقة:
# flutter analyze
# flutter test
# flutter build appbundle --releaseالمرجع الرسمي
للتفاصيل الخاصة بإصدار الأداة وبيئة التشغيل، راجع توثيق تحديث Gradle في Flutter. قد تختلف أسماء القوائم بين الإصدارات؛ طابق الإعداد مع مشروعك قبل تطبيقه.
