حل مشكلة Flutter: Gradle Build Failed وأشهر أسبابها وطرق إصلاحها
حل مشكلة Flutter: Gradle Build Failed وأشهر أسبابها وطرق إصلاحها
إذا كنت تعمل على مشروع Flutter وحاولت تشغيل التطبيق على Android ثم ظهرت لك رسالة Gradle Build Failed، فلا تقلق؛ هذه من أكثر المشاكل التي قد تواجه مطوري Flutter، خصوصًا بعد تحديث Flutter أو Android Studio أو Java أو إحدى المكتبات المستخدمة في المشروع.
في هذا المقال سنتعرف على أشهر أسباب خطأ Gradle في Flutter، وكيفية تشخيص المشكلة وإصلاحها خطوة بخطوة.
أولًا: ما هو Gradle في Flutter؟
Gradle هو نظام بناء تستخدمه مشاريع Android، ولذلك يعتمد عليه Flutter عند بناء تطبيق Android.
عندما تنفذ أمرًا مثل:
“flutter run”
أو:
“flutter build apk”
يمر المشروع بمرحلة Android وGradle قبل إنشاء التطبيق.
وقد يحدث الخطأ بسبب عدم توافق إصدارات Flutter وGradle وAndroid Gradle Plugin وJava أو Kotlin مع بعضها.
1. ابدأ بتشخيص الخطأ
قبل تغيير أي ملف بشكل عشوائي، افتح Terminal داخل مشروع Flutter وشغّل:
“flutter doctor -v”
هذا الأمر يساعدك على معرفة إصدار Flutter وJava والأدوات المرتبطة ببناء التطبيق.
بعد ذلك جرّب:
“flutter clean”
ثم:
“flutter pub get”
ثم:
“flutter run”
إذا استمرت المشكلة، اقرأ الجزء الموجود أسفل:
“FAILURE: Build failed with an exception.”
فالرسالة التي تأتي بعدها غالبًا هي التي تحدد السبب الحقيقي للمشكلة.
2. مشكلة إصدار Java
من أكثر أسباب مشاكل Gradle شيوعًا عدم توافق إصدار Java مع Gradle أو أدوات Android المستخدمة في المشروع.
Flutter يعتمد على Java أثناء عملية بناء تطبيق Android، ويمكن معرفة إصدار Java المستخدم من خلال:
“flutter doctor -v”
إذا كنت تستخدم إصدار Java غير مناسب، فقد تظهر أخطاء مثل:
“Unsupported class file major version”
أو أخطاء مرتبطة بـ Groovy وGradle.
في هذه الحالة، تأكد أولًا من إصدار Java ومن إصدار Gradle وAndroid Gradle Plugin المستخدمين في المشروع.
3. تحديث Flutter قد يسبب مشكلة في مشروع قديم
إذا كان المشروع قديمًا وتم إنشاؤه باستخدام إصدار Flutter قديم، فقد تكون ملفات Android وGradle الموجودة داخله تعتمد على طريقة إعداد قديمة.
لذلك قد تحتاج إلى تحديث ملفات Android الخاصة بالمشروع عند الانتقال إلى إصدارات Flutter الحديثة، بدل تغيير إصدار Gradle بشكل عشوائي.
إذا كان المشروع يعمل على إصدار Flutter قديم ثم بدأت المشكلة بعد التحديث، راجع ملفات Gradle الخاصة بالمشروع وتأكد من توافقها مع إصدار Flutter الجديد.
4. مشكلة Android Gradle Plugin وKotlin
أحيانًا يكون Flutter نفسه محدثًا، لكن المشروع يستخدم إصدارًا قديمًا من Android Gradle Plugin أو Kotlin.
وهنا قد تظهر أخطاء أثناء مرحلة:
“assembleDebug”
أو:
“assembleRelease”
إذا ظهر لك خطأ متعلق بـ Kotlin، راجع إصدار Kotlin المستخدم في المشروع وتأكد من توافقه مع بقية أدوات البناء.
ولا تقم بنسخ إصدار من مشروع آخر بشكل عشوائي؛ لأن إصدار Kotlin المناسب يعتمد على إعداد المشروع والإصدارات الأخرى المستخدمة معه.
5. مشكلة Plugin قديم
سبب آخر شائع هو وجود package أو plugin قديم داخل المشروع.
على سبيل المثال، قد يكون المشروع يعمل بشكل طبيعي قبل إضافة package معينة، وبعد إضافتها يبدأ Gradle في الفشل.
للتأكد، راجع آخر package أضفتها للمشروع.
يمكنك أيضًا تشغيل:
“flutter pub outdated”
لمعرفة الحزم التي تحتاج إلى تحديث.
لكن انتبه: لا تقم بتحديث جميع الحزم مرة واحدة في مشروع كبير دون مراجعة التغييرات، لأن تحديث package واحدة قد يتطلب تحديث packages أخرى معها.
6. مشكلة AndroidX
إذا كان المشروع أو إحدى المكتبات يستخدم Android Support Libraries القديمة بينما باقي المشروع يعتمد على AndroidX، فقد تحدث تعارضات أثناء عملية البناء.
لذلك من الأفضل التأكد من أن المكتبات المستخدمة في المشروع متوافقة مع AndroidX، خصوصًا إذا كان المشروع قديمًا.
إذا ظهرت رسائل خطأ تحتوي على كلمات مثل:
“AndroidX”
أو:
“android.support”
فقد تكون المشكلة مرتبطة بتوافق المكتبات مع AndroidX.
7. جرّب تنظيف المشروع
في كثير من الحالات تكون المشكلة ناتجة عن ملفات build أو cache قديمة.
جرّب بالترتيب:
“flutter clean”
ثم:
“flutter pub get”
ثم:
“flutter run”
إذا لم تحل المشكلة، انتقل إلى قراءة رسالة الخطأ نفسها بدل تكرار أوامر التنظيف.
8. لا تغيّر Gradle Version بشكل عشوائي
من أكثر الأخطاء التي يقع فيها المبتدئون أنهم يرون:
“Gradle Build Failed”
فيقومون مباشرة بتغيير إصدار Gradle إلى إصدار عشوائي من الإنترنت.
وهذا قد يحول مشكلة واحدة إلى عدة مشاكل.
السبب أن هناك توافقًا بين عدة عناصر، منها:
- Flutter
- Android Gradle Plugin
- Gradle
- Java
- Kotlin
- Android SDK
لذلك يجب معرفة الإصدارات المستخدمة في المشروع أولًا، ثم اختيار التوافق المناسب.
9. مشكلة بعد تحديث Android Studio
إذا كان مشروعك يعمل بشكل طبيعي قبل تحديث Android Studio ثم توقف بعد التحديث، فمن المحتمل أن يكون هناك اختلاف في إصدار Java أو Gradle المستخدم في عملية البناء.
في هذه الحالة شغّل:
“flutter doctor -v”
وسجل إصدار Java الذي يستخدمه Flutter.
بعد ذلك راجع إصدار Gradle وAndroid Gradle Plugin في المشروع قبل إجراء أي تعديل.
أفضل طريقة لمعرفة سبب المشكلة
بدل تجربة عشرات الحلول من الإنترنت، اتبع هذه الخطوات:
الخطوة الأولى
شغّل:
“flutter doctor -v”
الخطوة الثانية
شغّل:
“flutter clean”
الخطوة الثالثة
شغّل:
“flutter pub get”
الخطوة الرابعة
حاول تشغيل المشروع:
“flutter run”
الخطوة الخامسة
إذا ظهر الخطأ مرة أخرى، ركّز على أول رسالة خطأ حقيقية بعد:
“What went wrong:”
لأن عبارة:
“Gradle Build Failed”
ليست السبب نفسه؛ هي فقط تعني أن عملية البناء فشلت.
الخلاصة
مشكلة Gradle Build Failed في Flutter ليس لها حل واحد يناسب كل المشاريع.
السبب قد يكون:
- إصدار Java غير متوافق.
- Gradle قديم أو غير مناسب.
- Android Gradle Plugin غير متوافق.
- إصدار Kotlin قديم.
- مشروع Flutter قديم.
- Plugin أو package غير متوافقة.
- مشكلة AndroidX.
- ملفات build أو cache قديمة.
لذلك أفضل حل هو تحديد رسالة الخطأ الأصلية أولًا، ثم معرفة إصدارات Flutter وJava وGradle وAndroid Gradle Plugin المستخدمة في المشروع.
وبمجرد معرفة السبب، يصبح إصلاح المشكلة أسهل بكثير من تغيير ملفات Gradle بشكل عشوائي.
نصيحة للمطورين
احتفظ دائمًا بنسخة احتياطية أو commit على Git قبل إجراء تغييرات كبيرة على ملفات Android وGradle، خصوصًا عند ترقية Flutter أو Android Studio.
الرجاء تسجيل الدخول لتتمكن من التعليق