أثناء تطوير تطبيقات Flutter قد نواجه أخطاء تبدو بسيطة من ظاهرها، لكنها تتحول إلى تحدٍ حقيقي يستنزف ساعات طويلة من البحث والتجربة، خصوصًا عندما يظهر الخطأ بعد تحديث Flutter أو ترقية المكتبات داخل المشروع.

ومن أكثر الأخطاء المربكة التي قد تواجه مطوري Flutter مؤخرًا الخطأ التالي:

Unhandled Exception: PlatformException(
channel-error,
Unable to establish connection on channel.,
null,
null
)

ورغم أن الرسالة تبدو عامة جدًا، إلا أن الوصول إلى السبب الحقيقي ليس بالأمر السهل، لأن المشكلة لا تكون غالبًا في الكود الذي كتبته، بل في طريقة بناء التطبيق نفسها.

في هذا المقال سأشرح سبب ظهور المشكلة، ولماذا تحدث غالبًا على Android فقط، بالإضافة إلى الحل النهائي دون الحاجة لتعطيل تحسينات الإصدار النهائي للتطبيق.

ظهرت هذه المشكلة لدي بعد تحديث بيئة العمل بالكامل، حيث قمت بالآتي:

في البداية بدا كل شيء طبيعيًا، ولم تظهر أي أخطاء أثناء الـ Build.

لكن بمجرد تشغيل التطبيق على Android ظهرت الرسالة التالية:

Unhandled Exception:
PlatformException(channel-error,
Unable to establish connection on channel.,
null,
null)

المثير للاهتمام أن التطبيق كان يعمل بشكل طبيعي على iOS بدون أي مشاكل.

وهنا بدأ البحث الحقيقي عن السبب.

يعتمد Flutter على ما يسمى Platform Channels لربط كود Dart مع الكود الأصلي الخاص بالنظام (Native Code).

فعند استخدام مكتبات مثل:

يقوم Flutter بإنشاء قنوات اتصال بين Dart و Android أو iOS.

لكن أثناء بناء نسخة Release على Android، يتم تشغيل أدوات تحسين مثل:

هذه الأدوات تحاول حذف الأكواد غير المستخدمة وتصغير التطبيق النهائي.

المشكلة أن ProGuard أحيانًا يعتبر بعض الكلاسات الخاصة بـ Flutter Plugins غير مستخدمة، فيقوم بحذفها أثناء البناء.

وبالتالي تفشل عملية إنشاء القنوات بين Dart و Native ويظهر الخطأ:

Unable to establish connection on channel

خلال البحث وجدت اقتراحًا متكررًا وهو تعطيل عمليتي التصغير وإزالة الموارد داخل الملف:

android/app/build.gradle

داخل قسم Release:

release {
    minifyEnabled false
    shrinkResources false
}

وبالفعل اختفى الخطأ مباشرة وعاد التطبيق للعمل.

لكن هذا ليس الحل الصحيح.

لأن هاتين الخاصيتين مسؤولتان عن:

وتعطيلهما يعني خسارة جزء مهم من تحسينات التطبيق النهائي.

بعد تتبع عملية الـ Build ومراجعة سلوك Flutter مع R8 و ProGuard اتضح أن المشكلة تحدث بسبب حذف بعض الكلاسات الخاصة بالـ Plugins أثناء التصغير.

ومن الأمثلة التي قد تتأثر:

io.flutter.embedding.engine.plugins.FlutterPlugin

أو مكتبات مثل:

path_provider
shared_preferences

عندما يتم حذف هذه الكلاسات يفشل Flutter في تسجيل الـ Plugins وبالتالي تنقطع القنوات.

الحل الحقيقي هو منع ProGuard من حذف كلاسـات Flutter المهمة.

قم بإنشاء ملف جديد داخل مشروع Android باسم:

proguard-rules.pro

ثم أضف داخله:

-if class * implements io.flutter.embedding.engine.plugins.FlutterPlugin
-keep,allowshrinking,allowobfuscation class <1>

-keep class io.flutter.plugins.pathprovider.** { *; }

بعد ذلك افتح:

android/app/build.gradle

وتأكد من إضافة الملف داخل إعدادات Release:

release {
    minifyEnabled true
    shrinkResources true

    proguardFiles
        getDefaultProguardFile(
            'proguard-android-optimize.txt'
        ),
        'proguard-rules.pro'
}

بهذه الطريقة تستمر تحسينات R8 و ProGuard بالعمل بدون حذف كود Flutter المهم.

في بعض الحالات — خصوصًا بعد تحديث Flutter أو تغيير بنية المشروع — قد لا يتم تسجيل الإضافات تلقائيًا.

افتح الملف:

android/app/src/main/kotlin/your/package/name/MainActivity.kt

أضف الاستيراد التالي:

import io.flutter.plugins.GeneratedPluginRegistrant

ثم داخل:

override fun configureFlutterEngine(
    flutterEngine: FlutterEngine
) {
    super.configureFlutterEngine(flutterEngine)

    GeneratedPluginRegistrant.registerWith(
        flutterEngine
    )
}

هذه الخطوة تضمن تسجيل جميع الـ Plugins يدويًا حتى لو فشل Flutter في اكتشافها أثناء التشغيل.

إذا ظهرت لديك مشكلة:

PlatformException(
channel-error,
Unable to establish connection on channel
)

بعد تحديث Flutter أو المكتبات، فلا تتجه مباشرة لتعطيل:

minifyEnabled
shrinkResources

لأن هذا مجرد حل مؤقت.

السبب الحقيقي غالبًا يكون في أن ProGuard أو R8 قام بحذف بعض كلاسـات Flutter Plugins أثناء بناء نسخة Release.

والحل الصحيح يكون عبر:

بهذه الطريقة ستحافظ على تحسينات الإصدار النهائي وتتفادى المشكلة نهائيًا دون التضحية بأداء التطبيق أو حجمه.