← بازگشت به وبلاگ

چگونه پروکسی را در اندروید استودیو و گرادل تنظیم کنیم: gradle.properties و SDK Manager

نحوه صحیح نوشتن پروکسی در gradle.properties، تنظیم مدیر SDK و Android Studio و همچنین رفع رایج‌ترین خطاهای همگام‌سازی Gradle را بررسی می‌کنیم.

📅۲۲ آبان ۱۴۰۵

اگر Android Studio در مرحله همگام‌سازی Gradle «متوقف» شده باشد، SDK Manager اجزای لازم را بارگیری نکند و وابستگی‌ها از Maven Central دانلود نشوند — در 80% موارد مشکل در کد نیست، بلکه در محیط شبکه است. فایروال شرکتی، VPN، مسدود کردن IP مخزن یا فقط عدم دسترسی مستقیم به اینترنت — همه این‌ها با تنظیم صحیح پروکسی در سه سطح: IDE، Gradle و SDK Manager قابل حل است. بیایید بررسی کنیم که چگونه پروکسی را به درستی و بدون خطاهای اضافی همگام‌سازی کنیم.

چرا توسعه‌دهنده Android به پروکسی نیاز دارد

بیشتر اوقات پروکسی در ارتباط با Android Studio در چند سناریو استفاده می‌شود. اولین سناریو — شبکه شرکتی، جایی که دسترسی مستقیم به اینترنت مسدود شده و تمام ترافیک، از جمله درخواست‌ها به google()، mavenCentral() و dl.google.com، باید از طریق سرور پروکسی شرکت انجام شود. سناریو دوم — دور زدن محدودیت‌های منطقه‌ای: برخی از اجزای SDK، API خدمات Google Play یا مخازن شخص ثالث به‌طور مستقیم از کشورهای خاص در دسترس نیستند و توسعه‌دهنده مجبور است ترافیک را از طریق IP یک مکان جغرافیایی دیگر مسیریابی کند.

سناریوی سوم — تست عملکرد وابسته به جغرافیا در برنامه. اگر برنامه محتوای مختلف، قیمت‌ها یا تبلیغات را بسته به کشور کاربر نشان دهد، مهندسان QA و توسعه‌دهندگان باید درخواست‌ها را از منطقه مورد نظر در مرحله ساخت و اشکال‌زدایی شبیه‌سازی کنند، بدون اینکه منتظر انتشار باشند. سناریوی چهارم — کار با رنرهای CI/CD که به‌طور فیزیکی در مراکز داده با دسترسی محدود به خدمات خاص قرار دارند و پروکسی تنها راه «دست‌یابی» به مخزن یا API مورد نظر می‌شود.

در تمام این موارد منطق یکی است: Gradle، SDK Manager و خود IDE باید آدرس، پورت و در صورت نیاز، اطلاعات اعتبار پروکسی را بدانند، در غیر این صورت همگام‌سازی پروژه با زمان‌تایم‌ها یا خطاهای اتصال مواجه خواهد شد.

کدام نوع پروکسی برای توسعه انتخاب کنیم

برای توسعه و تست، مهم‌تر از ناشناس بودن، ثبات اتصال و درصد پایین قطع ارتباط در طول بارگیری‌های طولانی (به عنوان مثال، ابزارهای پلتفرم Android SDK صدها مگابایت حجم دارند) است. در زیر — مقایسه انواع پروکسی در ارتباط با وظایف توسعه‌دهنده Android.

نوع پروکسی کی استفاده کنیم ویژگی‌ها
پروکسی دیتاسنتر بارگیری SDK، همگام‌سازی Gradle، CI/CD سرعت بالا، قیمت پایین، پایدار برای بارگیری‌های بزرگ
پروکسی‌های مسکونی تست API و محتوای وابسته به جغرافیا IP کاربران واقعی، کمتر مسدود می‌شوند
پروکسی‌های موبایل تست API‌های موبایل و اعلان‌های فشار از یک کشور خاص IP اپراتورهای تلفن همراه، نزدیک‌ترین به ترافیک موبایل واقعی

برای همگام‌سازی پاک Gradle و دانلود وابستگی‌ها، بهتر است از پروکسی دیتاسنتر استفاده کنید — آن‌ها سرعت بالای ثابتی بدون تأخیر اضافی ارائه می‌دهند. اما اگر هدف این است که بررسی کنید چگونه backend برنامه به کاربر از کشور دیگر پاسخ می‌دهد، پروکسی‌های مسکونی یا 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 سفارشی دارید که API خارجی را فراخوانی می‌کند).

تنظیم پروکسی در خود 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 در Settings بر خود IDE (پلاگین‌ها، به‌روزرسانی‌ها) تأثیر می‌گذارد، در حالی که پارامترهای موجود در gradle.properties بر فرآیند ساخت Gradle تأثیر می‌گذارند. این دو مکانیزم مستقل هستند و برای کارکرد کامل از طریق پروکسی معمولاً باید هر دو را تنظیم کنید.

پروکسی برای SDK Manager

SDK Manager — یک جزء جداگانه است که پلتفرم‌های Android، build-tools، شبیه‌سازها و تصاویر سیستم را دانلود می‌کند. این ابزار دارای پیکربندی پروکسی خاص خود است که به‌طور تاریخی از طریق همان تنظیمات سیستم 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 مفید است، جایی که متغیرهای محیطی یک بار در سطح job تنظیم می‌شوند و به‌طور خودکار توسط تمام مراحل بعدی ساخت گرفته می‌شوند، بدون نیاز به ویرایش فایل‌های پروژه.

خطاهای رایج همگام‌سازی و راه‌حل‌های آن‌ها

بیایید رایج‌ترین خطاهایی را که توسعه‌دهندگان هنگام تنظیم پروکسی با آن‌ها مواجه می‌شوند، بررسی کنیم و مراحل خاص برای رفع آن‌ها را مرور کنیم.

خطا علت راه‌حل
Connection timed out پروکسی مشخص نشده یا در دسترس نیست میزبان/پورت را در gradle.properties بررسی کنید، دسترسی پروکسی را از طریق curl آزمایش کنید
407 Proxy Authentication Required نام کاربری/رمز عبور ارسال نشده است systemProp.http.proxyUser و systemProp.http.proxyPassword را اضافه کنید
Unable to resolve host DNS-رزولوشن از طریق پروکسی انجام نمی‌شود به‌جای http از socksProxyHost برای 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 دارند (به عنوان مثال، تست محدودیت‌های API از آدرس‌های مختلف)، راحت‌تر است که از خدمات پروکسی با مجموعه‌ای از آدرس‌ها و یک نام کاربری واحد استفاده کنید — در این صورت چرخش در سمت ارائه‌دهنده تنظیم می‌شود و فقط پورت جلسه در gradle.properties تغییر می‌کند، بدون نیاز به بازنویسی پیکربندی کل پروژه.

چک‌لیست تشخیص

اگر پس از تمام تنظیمات همگام‌سازی همچنان دچار مشکل هستید، به ترتیب موارد زیر را بررسی کنید:

  • دسترس‌پذیری پروکسی را به‌طور مستقیم با دستور curl -x http://proxy.example.com:8080 https://dl.google.com بررسی کنید
  • مطمئن شوید که تنظیمات هم در Settings → HTTP Proxy و هم در gradle.properties به‌طور همزمان مشخص شده‌اند
  • کش Gradle را پاک کنید: ./gradlew --stop و پوشه .gradle/caches را حذف کنید
  • بررسی کنید که در فایل هیچ فضای اضافی و یا علامت نقل قولی در اطراف مقادیر میزبان/پورت وجود نداشته باشد
  • اگر از SOCKS5 استفاده می‌شود — به‌جای http، socksProxyHost/socksProxyPort را مشخص کنید
  • برای پروکسی‌های MITM شرکتی، گواهی را به مخزن گواهی‌های معتبر JDK وارد کنید (keytool -import)
  • پس از هر تغییری در فایل‌های properties، Android Studio و Gradle Daemon را دوباره راه‌اندازی کنید

نتیجه‌گیری

تنظیم پروکسی در توسعه Android — کاری است که باید در سه سطح انجام شود: تنظیمات سیستم Android Studio برای خود IDE، پارامترهای systemProp در gradle.properties برای فرآیند ساخت، و پیکربندی جداگانه برای ابزارهای مستقل مانند sdkmanager. بیشتر خطاهای همگام‌سازی به‌دلیل این است که یکی از سطوح تنظیم شده و دیگری فراموش شده است، یا به‌دلیل عدم احراز هویت در پروکسی که به آن نیاز دارد.

اگر هدف فقط بارگیری پایدار وابستگی‌ها و اجزای SDK از طریق پروکسی کاری است، پروکسی‌های دیتاسنتر گزینه‌های عالی هستند — آن‌ها سریع و بدون تأخیر اضافی در بارگیری‌های بزرگ عمل می‌کنند. و اگر نیاز به تست رفتار برنامه برای کاربر از یک کشور خاص یا از یک اپراتور موبایل دارید، به پروکسی‌های مسکونی یا IP‌های موبایل نگاهی بیندازید — آن‌ها تصویر واقعی‌تری از رفتار خدمات در مناطق مختلف ارائه می‌دهند.