إذا كانت Android Studio "تتجمد" في مرحلة مزامنة Gradle، ولا يقوم SDK Manager بتحميل المكونات، ولا يتم تنزيل التبعيات من Maven Central - في 80% من الحالات تكون المشكلة ليست في الكود، بل في البيئة الشبكية. جدار الحماية المؤسسي، VPN، حظر IP المستودع أو ببساطة عدم وجود وصول مباشر إلى الإنترنت - كل ذلك يمكن حله من خلال إعداد البروكسي بشكل صحيح على ثلاثة مستويات: IDE و Gradle و SDK Manager. دعونا نستعرض كيفية كتابة البروكسي بشكل صحيح وبدون أخطاء مزامنة غير ضرورية.
لماذا يحتاج مطور Android إلى بروكسي
غالبًا ما يتم استخدام البروكسي مع Android Studio في عدة سيناريوهات. الأول - الشبكة المؤسسية، حيث يتم إغلاق الوصول المباشر إلى الإنترنت، ويجب أن يمر كل حركة المرور، بما في ذلك الطلبات إلى google() و mavenCentral() و dl.google.com، عبر خادم البروكسي الخاص بالشركة. الثاني - تجاوز القيود الإقليمية: بعض مكونات SDK، واجهات برمجة التطبيقات لـ Google Play Services أو المستودعات الخارجية غير متاحة مباشرة من دول معينة، ويضطر المطور إلى توجيه حركة المرور عبر IP لموقع جغرافي آخر.
السيناريو الثالث - اختبار الوظائف المعتمدة على الموقع الجغرافي للتطبيق. إذا كان التطبيق يعرض محتوى وأسعار وإعلانات مختلفة اعتمادًا على بلد المستخدم، يحتاج مهندسو الجودة والمطورون إلى محاكاة الطلبات من المنطقة المطلوبة حتى في مرحلة البناء وتصحيح الأخطاء، دون انتظار الإصدار. الرابع - العمل مع أدوات CI/CD التي تقع فعليًا في مراكز البيانات ذات الوصول المحدود إلى خدمات معينة، ويصبح البروكسي هو الطريقة الوحيدة "للوصول" إلى المستودع أو واجهة برمجة التطبيقات المطلوبة.
في جميع هذه الحالات، المنطق هو نفسه: يجب أن تعرف Gradle و SDK Manager و IDE نفسها عنوان البروكسي ورقم المنفذ، وإذا لزم الأمر، بيانات اعتماد خادم البروكسي، وإلا ستفشل مزامنة المشروع مع مهلات أو أخطاء في الاتصال.
أي نوع من البروكسي يجب اختياره للتطوير
بالنسبة للتطوير والاختبار، فإن الأهمية ليست في الخصوصية بقدر ما هي في استقرار الاتصال ونسبة الانقطاعات المنخفضة أثناء التحميلات الطويلة (على سبيل المثال، أدوات منصة Android SDK تزن مئات الميجابايت). أدناه - مقارنة بين أنواع البروكسي فيما يتعلق بمهام مطور Android.
| نوع البروكسي | متى تستخدم | الميزات |
|---|---|---|
| بروكسي مراكز البيانات | تحميل SDK، مزامنة Gradle، CI/CD | سرعة عالية، تكلفة منخفضة، مستقرة للتحميلات الكبيرة |
| بروكسي سكنية | اختبار واجهات برمجة التطبيقات المعتمدة على الموقع والمحتوى | IP لمستخدمين حقيقيين، نادرًا ما يتم حظرها من قبل الخدمات |
| بروكسي موبايل | اختبار واجهات برمجة التطبيقات المحمولة وإشعارات الدفع من دولة معينة | IP لمشغلي الاتصالات، قريبة جدًا من حركة المرور المحمولة الحقيقية |
من أجل مزامنة Gradle النظيفة وتنزيل التبعيات، من الأفضل استخدام بروكسي مراكز البيانات - فهي توفر سرعة عالية مستقرة بدون تأخيرات غير ضرورية. إذا كانت المهمة هي التحقق من كيفية استجابة واجهة برمجة التطبيقات لمستخدم من دولة أخرى، فإن البروكسي السكنية أو IP المحمولة ستكون أكثر ملاءمة.
إعداد البروكسي في gradle.properties
ملف gradle.properties هو المكان الرئيسي الذي يبحث فيه Gradle عن إعدادات البروكسي لاتصالات HTTP و HTTPS. يمكن أن يكون الملف في جذر المشروع (يعمل فقط لهذا المشروع) أو في الدليل العالمي ~/.gradle/gradle.properties (يعمل لجميع المشاريع على الجهاز). من المستحسن استخدام الخيار الثاني للعمل المستمر عبر البروكسي.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# اختياري - الاستثناءات التي تذهب مباشرة، متجاوزة البروكسي
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
بعد حفظ الملف، تأكد من الضغط على File → Sync Project with Gradle Files أو أيقونة "الفيل" في شريط الأدوات. إذا لم تلتقط IDE التغييرات تلقائيًا، أعد تشغيل Android Studio - أحيانًا يحتفظ ذاكرة التخزين المؤقت لإعدادات البروكسي حتى إعادة تشغيل عملية Gradle Daemon.
نقطة مهمة: المعلمات systemProp.* تعمل على مستوى JVM الذي يتم فيه تنفيذ Gradle، لذلك تؤثر ليس فقط على تنزيل التبعيات، ولكن أيضًا على أي طلبات شبكة داخل نصوص البناء (على سبيل المثال، إذا كان لديك مهمة Gradle مخصصة تستدعي واجهة برمجة التطبيقات الخارجية).
إعداد البروكسي في Android Studio نفسها
بالإضافة إلى Gradle، تحتوي IDE على إعدادات شبكة خاصة بها - وهي ضرورية لعمل المكونات الإضافية، وتحديثات IDE، والتحقق من التراخيص وبعض الميزات مثل الاقتراحات من Google. يمكنك فتحها عبر File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (على macOS - Android Studio → Preferences).
في النافذة المفتوحة، اختر Manual proxy configuration، وحدد المضيف ورقم المنفذ، وإذا لزم الأمر، ضع علامة على Proxy authentication وأدخل اسم المستخدم وكلمة المرور. هناك أيضًا زر مريح Check connection - أدخل عنوان URL تجريبي (مثل https://dl.google.com) واضغط عليه للتأكد من أن الاتصال يعمل بشكل صحيح قبل بدء مزامنة المشروع بشكل كامل.
من المهم فهم الفرق
تؤثر إعدادات HTTP Proxy في الإعدادات على IDE نفسها (المكونات الإضافية، التحديثات)، بينما تؤثر المعلمات في gradle.properties على عملية بناء Gradle. هذان آليتان مستقلتان، وللعمل بشكل كامل عبر البروكسي، عادةً ما تحتاج إلى إعداد كلاهما.
بروكسي لـ SDK Manager
SDK Manager هو مكون منفصل يقوم بتنزيل منصات Android، وأدوات البناء، والمحاكيات، وصور النظام. لديه تكوين بروكسي خاص به، الذي يتم تعيينه تاريخيًا عبر نفس إعدادات النظام IDE، ولكن عند العمل عبر sdkmanager المستقل (أداة CLI من سطر الأوامر)، يجب تمرير المعلمات بشكل صريح عبر علامات JVM.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
إذا تم تشغيل sdkmanager عبر سكربت، يمكنك كتابة البروكسي مباشرة في متغير البيئة JAVA_OPTS، الذي يقرأه الملف التنفيذي:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
خطأ شائع هو إعداد البروكسي في Android Studio، ولكن نسيان الأدوات المستقلة مثل sdkmanager أو avdmanager، التي تعمل كعملية Java منفصلة ولا ترث إعدادات IDE تلقائيًا.
بروكسي لـ gradlew ومتغيرات البيئة
إذا كنت تقوم ببناء المشروع من الطرفية عبر لفافة ./gradlew، متجاوزًا IDE (على سبيل المثال، في CI/CD أو ببساطة من العادة)، يمكنك تمرير البروكسي مباشرة في الأمر دون تغيير gradle.properties:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
للاستخدام المستمر، من الأسهل تعيين متغير البيئة GRADLE_OPTS في ملف تعريف الصدفة (.bashrc، .zshrc لـ Linux/macOS أو متغيرات البيئة في Windows):
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
هذا مفيد بشكل خاص في أدوات CI مثل GitHub Actions و GitLab CI أو Jenkins، حيث يتم تعيين متغيرات البيئة مرة واحدة على مستوى المهمة ويتم التقاطها تلقائيًا من قبل جميع خطوات البناء التالية، دون الحاجة إلى تعديل ملفات المشروع.
الأخطاء الشائعة في المزامنة وحلولها
دعونا نستعرض أكثر الأخطاء شيوعًا التي يواجهها المطورون عند إعداد البروكسي، والخطوات المحددة لحلها.
| الخطأ | السبب | الحل |
|---|---|---|
| Connection timed out | لم يتم تحديد البروكسي أو غير متاح | تحقق من المضيف/المنفذ في gradle.properties، واختبر توفر البروكسي عبر curl |
| 407 Proxy Authentication Required | لم يتم تمرير اسم المستخدم/كلمة المرور | أضف systemProp.http.proxyUser و systemProp.http.proxyPassword |
| Unable to resolve host | لا يتم إجراء حل DNS عبر البروكسي | استخدم socksProxyHost بدلاً من http لـ SOCKS5 مع DNS بعيد |
| Could not GET 'https://dl.google.com/...' | تم تعيين إعدادات Gradle، ولكن في IDE - لا (أو العكس) | قم بمزامنة الإعدادات في كلا المكانين: Settings → HTTP Proxy و gradle.properties |
| SSL handshake failed | يقوم البروكسي باعتراض SSL (MITM المؤسسي) | قم باستيراد الشهادة الجذرية للبروكسي إلى cacerts في JDK الخاص بك |
إذا حدث الخطأ عند تنزيل عناصر Maven معينة (مثل مكتبات androidx.*)، من المفيد مؤقتًا تشغيل سجل Gradle الموسع باستخدام الأمر ./gradlew build --info - في الإخراج، سترى الطلب الذي يحدث فيه انقطاع الاتصال ورمز الاستجابة الذي يعود به الخادم.
بروكسي مع المصادقة: اسم المستخدم وكلمة المرور
إذا كان البروكسي يتطلب مصادقة (وهي حالة قياسية لخدمات البروكسي المدفوعة والبوابات المؤسسية)، يجب إضافة سطرين آخرين إلى gradle.properties:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
تخزين كلمة مرور البروكسي في نص واضح في gradle.properties الخاص بالمشروع، الذي يتم إدخاله في نظام التحكم في الإصدارات - هو ممارسة سيئة. استخدم ملفًا عالميًا في الدليل المنزلي للمستخدم، الذي لا يتم التزامه في Git، أو مرر كلمة المرور عبر متغيرات البيئة في مرحلة CI/CD، حتى لا تتسرب الأسرار إلى المستودع.
بالنسبة للسيناريوهات التي تتطلب تدوير IP (مثل اختبار حدود واجهة برمجة التطبيقات من عناوين مختلفة)، من الأفضل استخدام خدمات البروكسي مع مجموعة جاهزة من العناوين واسم مستخدم واحد - حيث يتم إعداد التدوير على جانب المزود، وفي gradle.properties يتم تغيير المنفذ فقط، دون إعادة كتابة تكوين المشروع بالكامل.
قائمة التحقق للتشخيص
إذا استمرت المزامنة في الفشل بعد جميع الإعدادات، اتبع النقاط التالية بالترتيب:
- تحقق من توفر البروكسي مباشرة باستخدام الأمر
curl -x http://proxy.example.com:8080 https://dl.google.com - تأكد من أن الإعدادات مكتوبة في كل من Settings → HTTP Proxy و gradle.properties في نفس الوقت
- قم بتنظيف ذاكرة التخزين المؤقت لـ Gradle:
./gradlew --stopواحذف المجلد.gradle/caches - تحقق من عدم وجود مسافات زائدة أو علامات اقتباس حول قيم المضيف/المنفذ في الملف
- إذا كنت تستخدم SOCKS5 - اكتب socksProxyHost/socksProxyPort بدلاً من http.proxyHost
- بالنسبة للبروكسيات المؤسسية MITM، قم باستيراد الشهادة إلى مخزن الشهادات الموثوقة في JDK (keytool -import)
- أعد تشغيل Android Studio و Gradle Daemon بعد أي تغييرات في ملفات الخصائص
الخاتمة
إعداد البروكسي في تطوير Android هو عمل على ثلاثة مستويات: إعدادات النظام في Android Studio لـ IDE نفسها، ومعلمات systemProp في gradle.properties لعملية البناء، وتكوين منفصل لأدوات مستقلة مثل sdkmanager. معظم أخطاء المزامنة تحدث بسبب أن أحد المستويات تم إعداده، بينما تم نسيان الآخر، أو بسبب عدم وجود مصادقة على البروكسي الذي يتطلبها.
إذا كانت المهمة هي ببساطة تنزيل التبعيات ومكونات SDK بشكل مستقر عبر بروكسي العمل، فإن بروكسي مراكز البيانات هي الخيار المثالي - فهي سريعة ولا تسبب تأخيرات غير ضرورية أثناء التحميلات الكبيرة. وإذا كنت بحاجة لاختبار كيفية تصرف التطبيق لمستخدم من دولة معينة أو من مشغل موبايل، فكر في البروكسي السكنية أو IP المحمولة - فهي تعطي صورة أكثر واقعية عن سلوك الخدمات في مناطق مختلفة.