178.22.122.100) یا الکترو (78.157.42.101) را روی کارت شبکه تنظیم کنید.
۲. به مسیر File > Invalidate Caches / Restart در اندروید استودیو بروید و تیک Clear File System Cache را بزنید.
۳. خط org.gradle.jvmargs=-Xmx4096m -XX:+UseParallelGC را در فایل gradle.properties قرار دهید تا خطای حافظه برطرف و سرعت کامپایل ۴ برابر شود.
گریدل (Gradle) موتور اصلی بیلد و مدیریت وابستگی ها در اکوسیستم توسعه اندروید است. با این حال، به دلیل تحریم های اینترنتی در ایران، پیچیدگی تنظیمات شبکه و سنگین بودن پردازش های کامپایل جاوا و کاتلین، تقریباً تمام برنامه نویسان در مسیر حرفه‌ای خود با خطاهای طاقت‌فرسای گریدل مواجه می‌شوند. در این راهنمای جامع، تمامی خطاهای رایج گریدل را به‌همراه راه‌حل های تست‌شده در سال ۲۰۲۶ و ترفندهای چند برابر کردن سرعت بیلد بررسی می‌کنیم.
جدول عیب یابی سریع خطاهای متداول گریدل
در جدول زیر، ۵ مورد از پرتکرارترین پیام های خطای گریدل و علت دقیق و راه‌حل ریشه‌ای آن ها آورده شده است:
| پیام خطا در Build Console | علت ریشه‌ای خطا | راهکار عملی رفع مشکل |
|---|---|---|
| Gradle project sync failed | مسدود بودن دسترسی به سرور مخازن گوگل (Google Maven) به دلیل فیلترینگ یا تحریم | تنظیم DNS تحریم‌شکن معتبر یا پیکربندی پروکسی محلی در gradle.properties |
| Could not resolve all artifacts | قطع شدن ارتباط اینترنت وسط دانلود کتابخانه یا تغییر نام/نسخه پکیج در مخزن | استفاده از دستور --refresh-dependencies و بررسی نسخه پایدار در نقشه راه برنامه نویسی اندروید |
| OutOfMemoryError: Java heap space | ناکافی بودن رم اختصاص داده‌شده به پردازش پس‌زمینه Daemon گریدل | افزایش سقف Heap با پارامتر -Xmx4096m در فایل تنظیمات گریدل و مطالعه آموزش بهینه سازی رم در اندروید |
| Unsupported class file major version | عدم تطابق نسخه جاوا (JDK) انتخاب‌شده در تنظیمات با نسخه Gradle و AGP | تنظیم Gradle JDK روی نسخه پیش‌فرض و سازگار (JDK ۱۷) در تنظیمات Build Tools |
| Connection timed out / Read timed out | پکت‌لاس شدید، پینگ بالا یا قطع و وصلی مکرر شبکه حین دریافت باینری های سنگین | دانلود دستی توزیع گریدل (Local Distribution) و فعال سازی قابلیت Offline Mode |
۱. راهکار قطعی رفع مشکل دانلود و تحریم گریدل در ایران
یکی از بزرگ‌ترین چالش های توسعه دهندگان ایرانی، خطای اتصال به dl.google.com و مخزن maven.google.com است. برای حل این مشکل سه روش استاندارد وجود دارد:
روش اول: استفاده از دی ان اس تحریم شکن
ساده‌ترین و پایدارترین روش، تنظیم DNSهای ضدتحریم روی آداپتور شبکه سیستم‌عامل (Windows یا macOS) است. بهترین DNSهای تست‌شده عبارتند از:
- شکن (Shecan): دی‌ان‌اس اول
178.22.122.100| دی‌ان‌اس دوم185.51.200.2 - الکترو (Electro): دی‌ان‌اس اول
78.157.42.101| دی‌ان‌اس دوم78.157.42.100 - بگذر (Begzar): دی‌ان‌اس اول
185.55.226.26| دی‌ان‌اس دوم185.55.225.25
روش دوم: تنظیم مستقیم پروکسی در gradle.properties
اگر از ابزار های تغییر آی‌پی یا نرم افزارهای پراکسی محلی (Local Proxy) استفاده می‌کنید، می‌توانید پورت محلی را مستقیماً به گریدل بشناسانید تا ترافیک بیلد از پراکسی عبور کند. فایل gradle.properties در ریشه پروژه یا مسیر کاربر (~/.gradle/gradle.properties) را باز کرده و خطوط زیر را اضافه کنید:
# پیکربندی پراکسی HTTP و HTTPS برای رفع مسدودی گریدل
systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=10809
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=10809
# آدرس هایی که نیازی به پراکسی ندارند
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.ir
نکته: پورت 10809 را با پورت نرم افزار پروکسی خود (مثلاً ۱۰۸۰۸ یا ۷۸۹۰) جایگزین کنید.
۲. حل خطای OutOfMemoryError و کمبود رم گریدل
هنگامی که پروژه هایی مدرن اندرویدی مبتنی بر معماری چندماژوله و ابزار هایی مانند آموزش معماری تمیز در اندروید یا کاتلین کامپوز را کامپایل می‌کنید، گریدل به حافظه RAM قابل‌توجهی نیاز دارد. تخصیص پیش‌فرض (معمولاً ۱ یا ۱.۵ گیگابایت) باعث کرش کردن پروسه بیلد و کندی شدید سیستم می‌شود.
برای برطرف کردن قطعی این مشکل، فایل gradle.properties را باز کرده و پارامتر jvmargs را مانند نمونه زیر بهینه سازی کنید:
# تخصیص رم بهینه به پروسه گریدل (۴ گیگابایت برای سیستم های با رم ۱۶ گیگابایت)
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -XX:+HeapDumpOnOutOfMemoryError -XX:+UseParallelGC
اگر سیستم شما دارای ۸ گیگابایت رم است، مقدار -Xmx2048m مناسب خواهد بود؛ اما برای سیستم های با رم ۱۶ و بالاتر، مقدار -Xmx4096m سرعت بیلد را تا ۲ برابر ارتقا می‌دهد.
۳. تکنیک های طلایی افزایش ۱۰ برابری سرعت بیلد اندروید استودیو
پس از حل خطاهای مسدودی و حافظه، با اعمال ۴ سوییچ کلیدی در فایل تنظیمات، کامپایل مجدد پروژه های را به سریع‌ترین حالت ممکن برسانید:
# فعال سازی پروسه پایدار Daemon برای جلوگیری از استارت مکرر JVM
org.gradle.daemon=true
# اجرای همزمان وظایف مستقل و ماژول های موازی
org.gradle.parallel=true
# فعال سازی کش بیلد برای استفاده از خروجی های قبلی تسک ها
org.gradle.caching=true
# پیکربندی کامپایل افزایشی
kapt.incremental.apt=true
kotlin.incremental=true
استفاده از حالت آفلاین (Gradle Offline Mode)
وقتی تمام کتابخانه های پروژه شما یک‌بار با موفقیت دانلود شدند، دیگر نیازی نیست گریدل در هر بار اجرای پروژه با سرور هایی خارجی ارتباط برقرار کند. برای فعال سازی حالت آفلاین:
- از منوی کناری سمت راست اندروید استودیو، پنل Gradle را باز کنید.
- روی آیکون Toggle Offline Mode (شبیه به یک سوکت با خط مورب) کلیک کنید.
- اکنون بیلدها به صورت محلی و با سرعت خیره‌کننده زیر ۵ ثانیه اجرا می‌شوند.
۴. حل خطای SDK Location Not Found
این خطا زمانی ظاهر می‌شود که اندروید استودیو نمی‌تواند مسیر پکیج های توسعه اندروید را پیدا کند. برای بررسی تنظیمات پیش‌نیازها و مسیر استاندارد ابزار ها، به راهنمای آموزش نصب و راه اندازی اندروید استودیو مراجعه کنید. همچنین می‌توانید با ایجاد فایلی به نام local.properties در پوشه اصلی پروژه، مسیر را صراحتاً قید کنید:
# مسیر استاندارد SDK در سیستم عامل ویندوز
sdk.dir=C:\\Users\\YourUsername\\AppData\\Local\\Android\\Sdk
نتیجه گیری و چک لیست نهایی
رفع مشکلات گریدل نیازمند درک صحیح از نحوه مدیریت شبکه، تخصیص حافظه و تفکیک مخازن است. با پیاده سازی تنظیمات ارائه شده در این راهنما، از یک‌سو از خطاهای تحریم و سینک ناکام در امان خواهید بود و از سوی دیگر بازدهی و سرعت روزمره کد نویسی خود را به حداکثر می‌رسانید.
پرسش های متداول توسعه دهندگان درباره خطاهای گریدل
مهم ترین دلیل خطای Gradle project sync failed در ایران چیست؟
اصلی ترین دلیل این خطا در ایران، مسدود بودن سرور هایی گوگل و مخزن Maven توسط فیلترینگ یا تحریم ها است. با تنظیم DNS تحریم شکن مانند شکن (۱۷۸.۲۲.۱۲۲.۱۰۰) یا تعریف پروکسی در gradle.properties مشکل به سرعت برطرف می شود.
بهترین مقدار رم برای org.gradle.jvmargs چقدر است؟
برای سیستم هایی با رم ۸ گیگابایت، مقدار -Xmx۲۰۴۸m و برای سیستم های با رم ۱۶ گیگابایت یا بالاتر مقدار -Xmx۴۰۹۶m بهترین تعادل را میان پایداری سیستم عامل و سرعت بالای بیلد ایجاد می کند.
چگونه حالت آفلاین گریدل را فعال کنیم تا بیلد سریع تر شود؟
از تب کناری Gradle در سمت راست اندروید استودیو، روی آیکون Toggle Offline Mode کلیک کنید. با فعال شدن این قابلیت، گریدل به جای بررسی سرور هایی آنلاین، کتابخانه ها را مستقیماً از کش سیستم بارگذاری می کند.
خطای Unsupported class file major version در گریدل نشانه چیست؟
این خطا نشان می دهد نسخه جاوا (JDK) فعال در اندروید استودیو با نسخه Gradle یا پلاگین اندروید (AGP) سازگاری ندارد. برای حل آن باید در تنظیمات Build Tools مسیر Gradle JDK را روی نسخه سازگار (معمولاً JDK ۱۷) قرار دهید.
تفاوت فایل build.gradle در سطح Project و Module چیست؟
فایل سطح پروژه تنظیمات و پلاگین های مشترک کل پروژه را مدیریت می کند؛ اما فایل سطح ماژول (Module) وابستگی ها، نسخه های minSdk ،targetSdk و قوانین بیلد مخصوص همان بخش برنامه را تعیین می نماید.
چگونه از قابلیت Configuration Cache در گریدل برای دو برابر کردن سرعت بیلد استفاده کنیم؟
با افزودن خط org.gradle.configuration-cache=true به فایل gradle.properties، گراف وظایف بیلد کش شده و در کامپایل های بعدی بدون پردازش مجدد تنظیمات اجرا می گردد.
دستور gradlew --stop چه زمانی کاربرد دارد و چه کاری انجام می دهد؟
این دستور تمامی دیمون های سرگردان و قفل شده گریدل را در حافظه رم خاتمه می دهد تا در صورت بروز خطاهای فریز یا اشغال بیهوده منابع، پردازش تمیز آغاز شود.
چگونه کش دانلودهای خراب گریدل را در پوشه .gradle به صورت کامل پاکسازی کنیم؟
کافی است پس از بستن اندروید استودیو، پوشه caches واقع در مسیر C:\Users\Username\.gradle را حذف کرده و مجددا پروژه را سینک فرمایید تا کتابخانه ها تمیز بارگذاری شوند.
امتیاز و نظرات
هنوز نظری ثبت نشده است. اولین نفر باشید.